Full-stack clinic operations platform for OPD queue management, diagnostic flow coordination, and staff override auditing.
CareFlow AI models the operational core of a modern outpatient clinic: front-desk intake, service-lane classification, deterministic priority queueing, wait-time estimation, diagnostic flow planning, and role-based staff actions — every consequential decision logged for accountability. The platform runs entirely on synthetic data for a fictional Dhaka clinic and provides operational workflow support only: it performs no diagnosis, treatment, or medical decision-making.
Status: portfolio project — production-style implementation with a full test suite, role-based access control, and a PostgreSQL + Docker Compose setup.
- Role-based clinic access — five staff roles with distinct navigation, page access, and action permissions, enforced by the backend and mirrored in the UI
- Patient intake and visit creation — search or register synthetic patients, then create OPD visits with complaint, urgency, and routing details
- Service-lane classification — rule-based routing of visits into seven operational lanes (emergency, consultation, diagnostics, pharmacy, billing, and more) with confidence and explanation
- Priority queue scoring — deterministic tier + score ordering (emergency tier first, then lane priority, waiting time, risk, and department load)
- Wait-time estimation — capacity-aware queue-wait and service-time estimates per visit
- Diagnostic/OPD flow planning — ordered step plans (registration, sample collection, imaging, consultation, pharmacy, billing) generated per visit
- Flow board with step advancement — clinic-wide board grouped by step status, with role-gated start/complete/skip/cancel transitions
- Staff override audit trail — accept/override decisions recorded per visit with system recommendation, staff decision, and mandatory reason
- Operations dashboard — live KPIs, service-lane load, department capacity, flow-step progress, and override activity
- Synthetic Dhaka clinic data — idempotent seed command with staggered, realistic visit times
| Layer | Technology |
|---|---|
| Backend | Django, Django REST Framework |
| Frontend | React, TypeScript, Vite, Tailwind CSS |
| Database | PostgreSQL |
| Auth | Django session authentication with CSRF protection |
| API client | Axios |
| Server state | TanStack Query |
| DevOps | Docker Compose |
| Testing | Django/DRF tests, Vitest, React Testing Library |
The React SPA calls the API through the Vite dev proxy (same-origin, so session cookies and CSRF work without CORS). DRF views validate input and permissions, then delegate all business rules to a service layer that writes to PostgreSQL and records audit entries.
flowchart LR
SPA["React SPA<br/>(TypeScript · TanStack Query · Axios)"]
Proxy["Vite proxy<br/>/api → backend"]
API["Django REST Framework<br/>(session auth · CSRF · role permissions)"]
Services["Service layer<br/>(classification · queue · wait · flow · overrides)"]
DB[("PostgreSQL")]
Audit["Audit log"]
SPA --> Proxy --> API --> Services --> DB
Services --> Audit
Details: docs/ARCHITECTURE.md
flowchart TD
A["Patient intake<br/>(search or register)"] --> B["Visit creation"]
B --> C["Service-lane classification"]
C --> D["Queue entry<br/>(mark waiting)"]
D --> E["Priority scoring<br/>(tier + score)"]
E --> F["Wait-time estimate"]
F --> G["Flow plan generation"]
G --> H["Step advancement<br/>(role-gated)"]
H --> I["Staff override audit"]
| Role | Dashboard | Queue | Intake | Visits | Flow Board | Typical actions |
|---|---|---|---|---|---|---|
| Admin | ✓ | ✓ | ✓ | ✓ | ✓ | Everything, including all overrides |
| Front Desk | ✓ | ✓ | ✓ | ✓ | — | Register patients/visits, classify, mark waiting |
| Triage Nurse | ✓ | ✓ | — | ✓ | ✓ (view) | Classify, recalculate priority, flow plans |
| Doctor | — | ✓ | — | ✓ | ✓ | Advance consultation/review steps |
| Diagnostics | — | ✓ | — | ✓ | ✓ | Wait estimates, flow plans, advance diagnostic steps |
Full matrices: docs/ROLE_PERMISSIONS.md
Prerequisites: Docker with the Compose plugin.
cp .env.example .env # adjust secrets if desired
docker compose up --buildThe backend container applies database migrations automatically on startup. Seeding the synthetic dataset is a manual step:
docker compose exec backend python manage.py seed_clinic_demo_data --resetThen open:
- Frontend: http://localhost:5173
- Backend health check: http://localhost:8000/api/v1/health/
Run PostgreSQL through compose and the apps directly on your machine:
# 1. Database
docker compose up -d postgres
# 2. Backend (uses the DB_* variables from .env)
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py seed_clinic_demo_data --reset
python manage.py runserver
# 3. Frontend (separate terminal)
cd frontend
npm install
npm run devThe Vite dev server proxies /api to http://127.0.0.1:8000 by default; inside Docker Compose the proxy target is switched to the backend service via VITE_API_PROXY_TARGET. Any reachable PostgreSQL instance works — point the DB_* variables in .env at it. The app fails fast with a clear error if the database variables are missing.
The seed command creates synthetic staff accounts for local portfolio review:
| Role | Username |
|---|---|
| Admin | cf_admin |
| Front Desk | cf_frontdesk |
| Triage Nurse | cf_triage |
| Doctor | cf_provider_1 |
| Diagnostics | cf_diagnostic |
Password for all seeded accounts: careflow-demo-123
These accounts exist only in locally seeded databases. The login screen intentionally does not display credentials.
Backend (requires a running PostgreSQL):
python manage.py makemigrations --check --dry-run
python manage.py check
python manage.py testFrontend:
cd frontend
npm run build
npm run test:run
npm run lint- All patient, staff, and visit data is synthetic and generated for workflow simulation.
- CareFlow AI performs no diagnosis, treatment recommendation, or medication recommendation.
- Classification, priority, and wait estimates are operational routing signals, not clinical judgments.
- The system is not validated for clinical use; see docs/SAFETY_AND_SCOPE.md.
careflow-ai/
├── accounts/ # Custom user model with clinic roles
├── api/ # API routing, auth endpoints, health check
├── audit/ # Audit log model and log_action() utility
├── catalog/ # Departments, service lanes, providers
├── patients/ # Synthetic patient records
├── visits/ # Visits, queue, classification, wait, flow, overrides
├── dashboard/ # Operations stats service and demo data seeding
├── config/ # Django settings, PostgreSQL configuration
├── frontend/ # React + TypeScript SPA (Vite, Tailwind)
└── docs/ # Architecture, API, roles, demo guide, safety
| Document | Contents |
|---|---|
| docs/ARCHITECTURE.md | System design, service layer, auth flow, data model |
| docs/API_REFERENCE.md | Endpoint overview with role permissions |
| docs/ROLE_PERMISSIONS.md | Page and action matrices per role |
| docs/DEMO_GUIDE.md | Seeding, walkthrough, screenshot capture guide |
| docs/SAFETY_AND_SCOPE.md | Synthetic data and non-clinical scope statement |
This project is licensed under the MIT License. See LICENSE.