Hospital Management Enterprise API

A production-oriented FastAPI modular monolith for hospital operations. It combines patient administration, clinical workflows, pharmacy, laboratory, inpatient care, billing, insurance, analytics and auditing in one runnable backend that can later be decomposed into services.

Capabilities

• JWT access and refresh tokens with refresh-token rotation and revocation
• Argon2 password hashing and nine-role RBAC
• Patient registration, demographics, emergency contacts, allergies and chronic conditions
• Departments, doctor profiles, consultation fees and weekly schedules
• Appointment booking and controlled lifecycle transitions
• Clinical encounters, vitals, diagnoses and encounter closure
• Medication catalogue, stock controls, e-prescriptions and partial/full dispensing
• Laboratory test catalogue, test orders, sample states and structured results
• Wards, rooms, beds, admission, occupancy and discharge
• Invoice line items, tax, discount, partial payment and idempotency
• Insurance providers, patient policies, claims and settlement reconciliation
• Executive dashboard, low-stock reporting and audit logs
• PostgreSQL and SQLite support
• Alembic migrations, Docker Compose, Redis, Celery, CI and exported OpenAPI

Architecture

Clients / Portals
      |
      v
FastAPI /api/v1
      |
      +-- Authentication and RBAC
      +-- Patient Administration
      +-- Appointments
      +-- Clinical Records
      +-- Pharmacy
      +-- Laboratory
      +-- Admissions and Beds
      +-- Billing and Insurance
      +-- Analytics and Audit
      |
      +--> PostgreSQL
      +--> Redis / Celery workers

This codebase is intentionally organized as a modular monolith. It offers transactional consistency for an initial product while keeping domain routes and models separated for future service extraction.

Roles

Role	Primary access
Administrator	All configuration, users, dashboards and audit logs
Doctor	Assigned appointments, encounters, diagnosis, prescriptions, lab orders and discharge
Nurse	Patient lookup, appointment support, vitals and inpatient visibility
Receptionist	Patient registration, appointments, admission and invoice preparation
Lab technician	Test catalogue, sample workflow and results
Pharmacist	Medication catalogue, stock and prescription dispensing
Accountant	Invoices, payments and revenue visibility
Insurance officer	Providers, policies, claims and settlement
Patient	Own profile, appointments, clinical results, prescriptions, admissions and invoices

Quick start with Docker

cp .env.example .env
docker compose up --build

Seed demonstration records:

docker compose exec api python -m scripts.seed

Open:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health: http://localhost:8000/api/v1/health
• Readiness: http://localhost:8000/api/v1/ready

Local setup without Docker

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
Copy-Item .env.example .env

Linux or macOS:

source .venv/bin/activate
cp .env.example .env

For local SQLite development, change .env:

DATABASE_URL=sqlite:///./hospital_api.db
ENVIRONMENT=development

Then run:

pip install -r requirements.txt
alembic upgrade head
python -m scripts.seed
uvicorn app.main:app --reload

Demo accounts

Every seeded account uses Password@123.

Role	Email
Administrator	admin@hospital.example.com
Doctor	doctor@hospital.example.com
Nurse	nurse@hospital.example.com
Receptionist	reception@hospital.example.com
Lab technician	lab@hospital.example.com
Pharmacist	pharmacy@hospital.example.com
Accountant	accounts@hospital.example.com
Insurance officer	insurance@hospital.example.com
Patient	patient@hospital.example.com

Change every demonstration password and the JWT secret before exposing the service.

Common workflow

1. Administrator creates departments and staff users.
2. Administrator creates the doctor profile and weekly schedule.
3. Reception registers a patient and books an appointment.
4. Reception or nursing checks the appointment in.
5. The assigned doctor opens an encounter.
6. Nursing records vitals and the doctor adds diagnoses.
7. The doctor creates prescriptions and laboratory orders.
8. Pharmacy dispenses medication while decrementing stock.
9. Laboratory records test results and completes the order.
10. Reception admits the patient to an available bed when required.
11. Accounting builds and issues an invoice.
12. Payments and insurance settlements reduce the invoice balance.
13. The doctor discharges the patient and the bed becomes available.

Selected endpoint groups

POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/admin/users
POST   /api/v1/departments
POST   /api/v1/doctors
POST   /api/v1/patients
POST   /api/v1/appointments
POST   /api/v1/clinical/encounters
POST   /api/v1/clinical/encounters/{id}/vitals
POST   /api/v1/clinical/encounters/{id}/diagnoses
POST   /api/v1/pharmacy/prescriptions
POST   /api/v1/pharmacy/prescriptions/{id}/dispense
POST   /api/v1/laboratory/orders
PUT    /api/v1/laboratory/order-items/{id}/result
POST   /api/v1/admissions
POST   /api/v1/admissions/{id}/discharge
POST   /api/v1/billing/invoices
POST   /api/v1/billing/invoices/{id}/payments
POST   /api/v1/billing/insurance/claims
GET    /api/v1/admin/dashboard

The complete contract is available in openapi.json and through Swagger.

Tests

pytest

The lifecycle test covers staff creation, patient registration, appointment check-in, encounter documentation, medication dispensing, laboratory completion, admission and discharge, invoice payment, insurance settlement, audit behavior and dashboard metrics.

Database migrations

alembic upgrade head
alembic downgrade -1
alembic revision --autogenerate -m "describe change"

Production containers automatically execute alembic upgrade head before starting the API.

Background jobs

Celery and Redis are included for appointment reminders and result notifications:

celery -A app.tasks.celery_app worker --loglevel=INFO

Replace the demonstration task bodies with adapters for an approved SMS, email or notification provider.

Production hardening checklist

• Replace the JWT secret and all seeded credentials.
• Terminate TLS at a trusted reverse proxy or load balancer.
• Restrict CORS to approved portal domains.
• Place PostgreSQL and Redis on private networks.
• Encrypt backups and define tested recovery objectives.
• Add centralized logs, metrics, traces and security alerts.
• Use a secrets manager rather than committed environment files.
• Add rate limiting, account lockout and MFA for privileged staff.
• Review the authorization policy for the institution's clinical governance model.
• Integrate approved payment, insurance, notification and identity providers.
• Add document storage, consent management, retention rules and data export/deletion procedures.
• Perform security, privacy, clinical safety and regulatory reviews before real patient use.

Important notice

This repository is an enterprise-style engineering reference and starter implementation. It is not automatically certified for any healthcare regulation or clinical use. Real deployment requires institution-specific security controls, privacy agreements, clinical validation, legal review, operational procedures and applicable regulatory compliance.