Health Care Management System — FastAPI Backend

A modern, robust healthcare management API built with FastAPI — delivering secure, scalable, and efficient healthcare services with real-time notifications.

• Docker & Docker Compose
• Python 3.11+ (for local development)

cp .env.example .env   # then set real passwords and SECRET_KEY
docker compose up --build -d

The API will be available at: http://localhost:8000 API Documentation: http://localhost:8000/docs

Set FIRST_ADMIN_EMAIL / FIRST_ADMIN_PASSWORD in .env to have an admin account created on first startup.

.
├── app/
│   ├── api/
│   │   ├── routes/           # API endpoint handlers
│   │   │   ├── auth.py
│   │   │   ├── user.py
│   │   │   ├── patient.py
│   │   │   ├── doctor.py
│   │   │   ├── appointment.py
│   │   │   └── medical_record.py
│   │   └── deps.py           # Auth and role dependencies
│   ├── core/                 # Core application logic
│   │   ├── config.py         # Configuration management
│   │   ├── security.py       # JWT and password hashing
│   │   ├── cache.py          # Redis response caching middleware
│   │   ├── rate_limiter.py   # Redis rate limiting middleware
│   │   ├── notifications.py  # Publishes appointment events to RabbitMQ
│   │   └── timeutils.py      # UTC normalization
│   ├── crud/                 # Database operations layer
│   ├── db/                   # SQLAlchemy models and session
│   ├── schemas/              # Pydantic schemas
│   └── tests/                # Test suites
├── docker-compose.yml        # Multi-service orchestration
├── Dockerfile                # API container
├── Dockerfile.notification   # Notification worker container
├── notification_service.py   # Async notification worker (RabbitMQ → email)
├── API_EXAMPLES.http         # Example requests
└── .env.example              # Environment template

The system runs as a multi-container application. Only the API port is published; the other services are reachable on the internal network.

# Production deployment
docker compose up --build -d

# View logs
docker compose logs -f app notification

# Stop services
docker compose down

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Install dependencies
pip install -r requirements-dev.txt

# Point the app at your services (or put these in .env)
export DATABASE_URL=postgresql://user:pass@localhost:5432/healthcare
export SECRET_KEY=dev-secret

# Run the application
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Redis and RabbitMQ are optional locally: caching and rate limiting fail open, and notifications are logged as errors when RabbitMQ is unreachable. Disable them with CACHE_ENABLED=false, RATE_LIMIT_ENABLED=false and NOTIFICATIONS_ENABLED=false.

• 🔐 Secure Authentication – JWT (HS256) bearer tokens, bcrypt password hashing
• 👥 Role-Based Access Control – Patient, Doctor, Staff and Admin roles
• 📅 Appointment Management – Availability windows, conflict detection, free slot lookup, rescheduling and cancellation
• 🩺 Medical Records – Doctor-authored records, readable by the patient
• ⚡ Real-time Notifications – Appointment events published to RabbitMQ and emailed by a worker
• 💾 Caching – Per-user Redis response caching, invalidated on writes
• 🚀 Rate Limiting – Per-IP request throttling
• 📊 Health Checks – Container and service health monitoring

All scheduling times are UTC. Timestamps with an offset are converted; timestamps without one are treated as UTC. Doctor availability is a weekly window (day_of_week 0 = Monday) and slots are 30 minutes.

User accounts link to a patient or doctor profile through reference_id.

• fastapi, uvicorn – Web framework and ASGI server
• pydantic, pydantic-settings, email-validator – Validation and settings
• sqlalchemy, psycopg2-binary – ORM and PostgreSQL driver
• PyJWT, bcrypt – Tokens and password hashing
• redis – Caching and rate limiting
• aio-pika – RabbitMQ publisher (API) and consumer (worker)
• aiosmtplib – Email delivery (worker)
• pytest, pytest-cov, httpx – Testing (requirements-dev.txt)

# Used by docker-compose.yml
DB_PASSWORD=your_secure_password
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=your_rabbitmq_password
SECRET_KEY=your_jwt_secret_key          # required when ENVIRONMENT=production

# Read by the app (compose sets these from the values above)
DATABASE_URL=postgresql://user:pass@db:5432/healthcare_db
REDIS_URL=redis://redis:6379/0
RABBITMQ_URL=amqp://user:pass@rabbitmq:5672/
ACCESS_TOKEN_EXPIRE_MINUTES=30
CACHE_ENABLED=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60
NOTIFICATIONS_ENABLED=true
FIRST_ADMIN_EMAIL=admin@example.com
FIRST_ADMIN_PASSWORD=change-me-please

# Notification worker (leave SMTP_SERVER empty to log emails instead of sending)
SMTP_SERVER=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=
SMTP_PASSWORD=
EMAIL_FROM=noreply@example.com

• app/core/config.py – Centralized configuration management
• docker-compose.yml – Service orchestration
• Dockerfile – Application container definition
• Dockerfile.notification – Worker container definition

1. Copy .env.example to .env and set real values
2. Run docker compose up --build -d
3. Access API at http://your-server:8000
4. Monitor services with docker compose logs -f

Tables are created automatically on startup. There are no migrations yet, so schema changes to an existing database must be applied manually.

• API: GET /health
• Database, Redis, RabbitMQ: automatic health checks in compose

• Multi-stage Docker builds for optimized image sizes
• Non-root user execution for enhanced security
• Connection pooling with pre-ping for database efficiency
• Request rate limiting to prevent abuse
• JWT token expiration for session security
• Password length validation (8–72 bytes) with bcrypt hashing

Tests use a throwaway SQLite database by default and never read DATABASE_URL. Set TEST_DATABASE_URL to run them against PostgreSQL (CI does this).

# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run specific test module
pytest app/tests/test_api.py -v

# Against PostgreSQL (the database is dropped and recreated)
TEST_DATABASE_URL=postgresql://test:test@localhost:5432/test pytest

1. Fork the repository
2. Create your feature branch

   git checkout -b feature/amazing-feature

3. Commit your changes

   git commit -m 'Add amazing feature'

4. Push to the branch

   git push origin feature/amazing-feature

5. Open a Pull Request

This project is licensed under the MIT License. See the LICENSE file for more information.

curl:

curl -X POST http://localhost:8000/api/appointments/ \
  -H "Authorization: Bearer <token_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": 1,
    "doctor_id": 2,
    "start_time": "2030-12-03T10:00:00",
    "end_time": "2030-12-03T10:30:00",
    "notes": "Consulta preventiva"
  }'

Python:

import requests

url = "http://localhost:8000/api/appointments/"
headers = {"Authorization": "Bearer <token_jwt>"}
payload = {
    "patient_id": 1,
    "doctor_id": 2,
    "start_time": "2030-12-03T10:00:00",
    "end_time": "2030-12-03T10:30:00",
    "notes": "Consulta preventiva",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())

See API_EXAMPLES.http for more requests.

Delivering secure, scalable healthcare APIs with cutting-edge technology.