Clinic Management API

Project Overview

Clinic Management API is a backend service for managing patients, doctors, appointments, notifications, and analytics in a clinic workflow. It provides a modular FastAPI codebase with SQLAlchemy persistence, Alembic migrations, and pytest-based test coverage for core business behavior.

Architecture

This project uses a modular monolith architecture. That means the application runs as one deployable service, but the code is split into clear domain modules so each area of the system stays easier to reason about, test, and extend.

Modules

• patients: patient records, profile updates, activation state, and paginated listing
• doctors: doctor records, availability fields, activation state, and paginated listing
• appointments: booking, rescheduling, lifecycle transitions, and appointment retrieval
• notifications: internal notification log records written from appointment events
• analytics: aggregated reporting for summary counts, doctor stats, and busiest time slots

Tech Stack

Technology	Purpose
FastAPI	HTTP API framework and routing
SQLAlchemy	ORM and database access layer
MySQL	Primary relational database for local/runtime use
Alembic	Schema migrations
Pydantic	Request/response validation and settings management
pytest	Automated testing
SQLite	In-memory database used in tests
FastAPI TestClient	API-level integration tests

Getting Started

Prerequisites

• Python 3.12+
• uv
• MySQL server running locally or on a reachable host
• A created MySQL database for this project

Steps to Run the Project

1. Clone the repository and install dependencies:

git clone https://github.com/Ad-pkh/Clinic-Management-API.git
cd FastApi
uv sync

2. Create a .env file in the project root:

DATABASE_URL=
API_KEY=
APP_NAME=
DEBUG=

3. Set DATABASE_URL using SQLAlchemy's MySQL URL format:

DATABASE_URL=mysql+pymysql://USER:PASSWORD@HOST:PORT/DB_NAME

4. Apply database migrations:

uv run alembic upgrade head

5. Start the API server:

uv run uvicorn app.main:app --reload

6. Open the API docs:

http://127.0.0.1:8000/docs

7. For protected endpoints, send this header with requests:

X-API-Key: <your API_KEY value>

API Endpoints

Patients

Method	Path	Description
POST	/patients	Create a patient
GET	/patients	List patients with pagination
GET	/patients/{patient_id}	Get patient by ID
PATCH	/patients/{patient_id}	Update patient details
DELETE	/patients/{patient_id}	Soft-deactivate a patient

Doctors

Method	Path	Description
POST	/doctors	Create a doctor
GET	/doctors	List doctors with pagination
GET	/doctors/{doctor_id}	Get doctor by ID
PATCH	/doctors/{doctor_id}	Update doctor details
DELETE	/doctors/{doctor_id}	Soft-deactivate a doctor

Appointments

Method	Path	Description
POST	/appointments	Book an appointment
GET	/appointments	List appointments with pagination and optional status filter
GET	/appointments/{appointment_id}	Get appointment by ID
PATCH	/appointments/{appointment_id}/confirm	Confirm a pending appointment
PATCH	/appointments/{appointment_id}/cancel	Cancel a pending or confirmed appointment
PATCH	/appointments/{appointment_id}/complete	Complete a confirmed appointment
PATCH	/appointments/{appointment_id}/reschedule	Reschedule a pending or confirmed appointment
GET	/appointments/{appointment_id}/notifications	List notification logs for one appointment

Analytics

Method	Path	Description
GET	/analytics/summary	Return high-level counts for appointments, patients, and doctors
GET	/analytics/doctors	Return aggregated doctor appointment stats
GET	/analytics/slots	Return the busiest appointment hours

System

Method	Path	Description
GET	/	Health check

State Machine

Appointment lifecycle:

PENDING
  |-- confirm --> CONFIRMED
  |-- cancel  --> CANCELLED

CONFIRMED
  |-- complete --> COMPLETED
  |-- cancel   --> CANCELLED

COMPLETED
  |-- no further transitions allowed

CANCELLED
  |-- no further transitions allowed

Running Tests

Run the full test suite with:

uv run pytest app/tests -q

The test suite covers:

• patient CRUD and pagination behavior
• doctor CRUD and duplicate validation
• appointment booking, transitions, rescheduling, and conflict handling
• notification log creation after appointment events
• SQLite in-memory test database setup with dependency overrides

Project Structure

FastApi/
├── alembic/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
├── app/
│   ├── core/
│   │   ├── config.py
│   │   ├── db.py
│   │   └── exceptions.py
│   ├── modules/
│   │   ├── analytics/
│   │   │   ├── router.py
│   │   │   └── service.py
│   │   ├── appointments/
│   │   │   ├── model.py
│   │   │   ├── router.py
│   │   │   ├── schema.py
│   │   │   └── service.py
│   │   ├── doctors/
│   │   │   ├── model.py
│   │   │   ├── router.py
│   │   │   ├── schema.py
│   │   │   └── service.py
│   │   ├── notifications/
│   │   │   ├── model.py
│   │   │   ├── schema.py
│   │   │   └── service.py
│   │   └── patients/
│   │       ├── model.py
│   │       ├── router.py
│   │       ├── schema.py
│   │       └── service.py
│   ├── shared/
│   │   ├── constants.py
│   │   ├── deps.py
│   │   ├── queries.py
│   │   └── utils.py
│   ├── tests/
│   │   ├── conftest.py
│   │   ├── test_appointments.py
│   │   ├── test_doctors.py
│   │   └── test_patients.py
│   ├── main.py
│   └── models_registry.py
├── .env
├── alembic.ini
├── pyproject.toml
├── README.md
└── requirements.txt