A full-stack, cloud-native hospital management system built with Python FastAPI for backend, React.js for frontend, and PostgreSQL for the database, deployed on AWS ECS Fargate with Terraform IaC and CI/CD via GitHub Actions.
Author: Johntoby for Borderless Tech Academy
- Features
- Tech Stack
- Architecture
- Screenshots
- Getting Started
- Local Development
- AWS Deployment
- API Documentation
- Load Testing
- Cost Breakdown
- Contributing
- License
- Patient Management — Register, update, and track patient records
- Doctor Management — Manage doctor profiles and specializations
- Appointment Scheduling — Book, reschedule, and cancel appointments
- Department Management — Organize hospital departments
- Dashboard & Analytics — Real-time statistics and visualizations
- Authentication & Authorization — JWT-based auth with role-based access control
- Auto-Scaling — Handles up to 500 concurrent users on AWS
- Observability — Prometheus metrics, CloudWatch logs and alarms
- Load Testing — Locust-based performance testing suite
| Layer | Technology |
|---|---|
| Frontend | React 18, Vite, Tailwind CSS, React Router, React Query, Recharts |
| Backend | Python 3.x, FastAPI, SQLAlchemy, Pydantic, Alembic |
| Database | PostgreSQL 16 |
| Auth | JWT (python-jose), bcrypt |
| Containerization | Docker, Docker Compose, Nginx |
| Cloud | AWS ECS Fargate, ALB, RDS, ECR, VPC, CloudWatch |
| IaC | Terraform |
| CI/CD | GitHub Actions |
| Load Testing | Locust |
| Monitoring | Prometheus, CloudWatch Alarms |
┌─────────────┐ ┌─────────────────────────────────────────────────┐
│ Client │ │ AWS Cloud │
│ (Browser) │──────▶│ ALB ──┬──▶ ECS Frontend (React/Nginx) │
└─────────────┘ │ │ │
│ └──▶ ECS Backend (FastAPI) ──▶ RDS (PG) │
└─────────────────────────────────────────────────┘
| Component | Details |
|---|---|
| Compute | ECS Fargate (serverless containers) |
| Database | RDS PostgreSQL 16, Multi-AZ, encrypted |
| Load Balancer | Application Load Balancer with path-based routing |
| Registry | Amazon ECR |
| Networking | VPC with public/private subnets across 2 AZs |
| Monitoring | CloudWatch Logs + Alarms, Prometheus metrics |
 |
 |
 |
 |
 |
 |
 |
 |
- Docker Desktop 24+
- Git
- (For AWS deployment) AWS CLI v2, Terraform >= 1.10.0
git clone https://github.com/your-username/borderless-hms.git
cd borderless-hms- Create a
.envfile from the example:
cp .env.example .envUpdate for local use:
POSTGRES_SERVER=postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=H0sp1talDev2024!
POSTGRES_DB=hospital_db
POSTGRES_SSL_MODE=disable
SECRET_KEY=local-dev-secret-key-change-in-production
ENVIRONMENT=development
DEBUG=true
BACKEND_CORS_ORIGINS=["http://localhost:3000","http://localhost:80","http://localhost:8080"]- Start all services:
docker compose up --build- Access the application:
| URL | Description |
|---|---|
| http://localhost:8080 | Full app (via Nginx proxy) |
| http://localhost:8000/api/v1/docs | Swagger API documentation |
- Default login:
| Username | Password | Role |
|---|---|---|
| admin | Admin@12345 | System Administrator |
- Stop services:
docker compose down # keeps data
docker compose down -v # full reset (deletes database)For the full local development guide (pgAdmin, rebuilding, logs), see localdev.md.
The application deploys to AWS ECS Fargate using Terraform. The full step-by-step deployment guide is available in aws-setup.md.
High-level steps:
- Configure AWS CLI
- Create
terraform.tfvarswith your secrets - Deploy ECR repositories
- Build & push Docker images
- Deploy full infrastructure (
terraform apply) - Verify via ALB DNS URL
CI/CD is handled by GitHub Actions — every push to main triggers:
Build → Test → Push to ECR → Deploy to ECS → Verify
The backend exposes a full OpenAPI/Swagger UI at /api/v1/docs.
| Group | Endpoints |
|---|---|
| Auth | POST /api/v1/auth/login, POST /api/v1/auth/register |
| Patients | GET/POST/PUT/DELETE /api/v1/patients |
| Doctors | GET/POST/PUT/DELETE /api/v1/doctors |
| Appointments | GET/POST/PUT/DELETE /api/v1/appointments |
| Stats | GET /api/v1/stats |
| Health | GET /health |
| Metrics | GET /metrics (Prometheus) |
Load tests are written with Locust and located in the load-tests/ directory.
cd load-tests
pip install locust
export LOAD_TEST_USERNAME=admin
export LOAD_TEST_PASSWORD=Admin@12345
locust -f locustfile.py --host=http://localhost:8080Open http://localhost:8089 to configure and start the test.
Production target: 50,000 concurrent users with auto-scaling up to 20 ECS tasks.
| Service | Monthly Cost |
|---|---|
| ECS Fargate (4 tasks) | ~$58 |
| RDS PostgreSQL (db.t3.medium, Multi-AZ) | ~$70 |
| ALB | ~$22 |
| NAT Gateway | ~$10 |
| ECR / CloudWatch / misc | ~$4 |
| Total | ~$164/month |
See aws-setup.md for tips on reducing costs for dev/staging environments.
borderless-hms/
├── backend/
│ ├── app/
│ │ ├── api/routes/ # FastAPI route handlers
│ │ ├── core/ # Config, security utilities
│ │ ├── db/ # Database models, session
│ │ ├── schemas/ # Pydantic schemas
│ │ └── main.py # App entry point
│ ├── Dockerfile
│ └── requirements.txt
├── frontend/
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── context/ # React context providers
│ │ ├── pages/ # Page components (Dashboard, Patients, etc.)
│ │ ├── services/ # API service layer (Axios)
│ │ ├── App.jsx
│ │ └── main.jsx
│ ├── Dockerfile
│ ├── nginx.conf
│ └── package.json
├── load-tests/
│ └── locustfile.py # Locust load test scenarios
├── screenshots/ # Application & infrastructure screenshots
├── .env.example # Environment variable template
├── nginx-proxy.conf # Local dev reverse proxy config
├── aws-setup.md # AWS deployment guide
├── localdev.md # Local development guide
├── architecture-diagram.png
└── LICENSE
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Copyright (c) 2026 John Idowu