# sushanttusharjoshi/predictive-care architecture

> Architecture diagram of the GitHub repository sushanttusharjoshi/predictive-care, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushanttusharjoshi/predictive-care
- Repository: https://github.com/sushanttusharjoshi/predictive-care

## Overview

1. **System shape**
   - This is a two-tier application: a **Next.js frontend** and a **FastAPI backend**.
   - The backend owns all clinical/business logic, persistence, ML inference, auth, and compliance logging.
   - The frontend is a presentation layer that calls backend APIs through a small API client.

2. **Primary runtime entry points**
   - Backend has two app entrypoints: `backend/app/main.py` and `backend/app/main_pg.py`.
   - This suggests two persistence modes or migrations: a legacy/local database path and the newer **async PostgreSQL** path.
   - The backend is the core service that exposes REST endpoints used by the UI and any tooling.

3. **Backend data layer**
   - `backend/app/data/` contains the storage boundary:
     - `database.py` and `database_pg.py` separate database implementations.
     - `models_pg.py` defines the PostgreSQL ORM/schema layer.
   - Data generation and ingestion are explicit subsystems:
     - `generate_synthetic.py` creates synthetic patients.
     - `ingest_synthea.py` imports realistic Synthea data or falls back to synthetic generation.
   - This means the repo is designed to bootstrap large datasets without external clinical systems.

4. **Domain services**
   - `backend/app/services/` is where business workflows live:
     - `auth.py` handles authentication and role-based access.
     - `audit.py` records compliance-sensitive activity.
     - `create_patient.py` encapsulates patient creation.
     - `reminders.py` and `trust_score.py` drive medication adherence features.
     - `groq_narratives.py` generates natural-language explanations through the Groq LLM.
   - These services are the main boundary between HTTP handlers and domain logic.

5. **HIPAA and compliance boundary**
   - `backend/app/middleware/hipaa.py` enforces request-time compliance logging.
   - The README indicates every PHI access is audit-logged with user, role, IP, user agent, and patient context.
   - The compliance flow is a core architectural concern, not a side feature: requests pass through **JWT auth → RBAC → HIPAA audit middleware → business logic**.
   - The `/hipaa/data-flow` endpoint is part documentation, part audit artifact.

6. **Machine learning subsystem**
   - `backend/app/ml/` contains model training and inference support.
   - `train.py` and `train_pg.py` indicate model training is tied to the backend’s storage mode.
   - `similar_patients.py` suggests patient-level similarity / cohort retrieval to support recommendations.
   - The README says the models are an **XGBoost + LightGBM ensemble** with SHAP explainability and scikit-learn utilities.
   - ML output is used for risk prediction, explanations, and model metrics visible through the API.

7. **Clinical workflow features**
   - The product is not just scoring; it also includes workflow controls:
     - medication reminders,
     - adherence trend views,
     - prediction explainability,
     - clinician feedback,
     - prediction override with documented reasoning,
     - scheduling recommendation with **human-in-the-loop approval**.
   - These features indicate a closed loop: model prediction → clinician review/feedback → possible retraining or override.
   - The architecture intentionally blocks autonomous scheduling decisions.

8. **Frontend structure**
   - The frontend uses the **Next.js App Router** under `frontend/app/`.
   - Pages are organized by workflow:
     - `dashboard/` for operational views,
     - `patients/` and `patient/[id]/` for patient detail and drill-down,
     - `alerts/` for reminders and exceptions,
     - `admin/` for privileged compliance/operations views.
   - `frontend/components/Nav.tsx` provides shared navigation, and `frontend/lib/api.ts` centralizes backend calls.
   - The UI is a consumer of backend APIs, not a separate domain engine.

9. **End-to-end data flow**
   - The dominant runtime path is:
     - user loads Next.js UI,
     - UI calls FastAPI endpoints,
     - backend authenticates and audits the request,
     - backend reads patient/ML data from PostgreSQL,
     - optional LLM or SHAP-based explanation generation runs,
     - response returns to the UI for visualization.
   - A second important path is offline/bootstrap:
     - generate or ingest patient data,
     - train models,
     - then serve inference and analytics from the backend.

10. **External services and infrastructure**
   - The backend integrates with:
     - **PostgreSQL 16** for persistence,
     - **Groq API** for narrative generation,
     - deployment on **Railway** for backend and **Vercel** for frontend.
   - Docker files and `docker-compose.yml` support local database + backend development.
   - The repo is configured for environment-variable-based secrets and runtime config.

11. **Supporting repo artifacts**
   - `backend/tests/test_health.py` shows at least a minimal API test surface.
   - `scripts/setup.sh` and the `Makefile` indicate the project is designed for repeatable local setup and developer onboarding.
   - `backend/.env.example` and separate requirements files reinforce the split between the legacy and PostgreSQL runtime paths.

12. **How to draw the architecture**
   - Draw three main boxes: **Frontend (Next.js)**, **Backend API (FastAPI)**, and **Data/ML services**.
   - Inside the backend, show separate lanes for **auth/compliance**, **patient/domain services**, **ML inference/training**, and **database access**.
   - Show external arrows to **PostgreSQL** and **Groq API**.
   - Emphasize that compliance logging and clinician approval are first-class flows, not afterthoughts.

Main entry points: [`backend/app/main.py`](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/main.py) (FastAPI App), [`frontend/app`](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app) (Next.js App), [`backend/app/data/database_pg.py`](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/database_pg.py) (Postgres DB), [`frontend/lib/api.ts`](https://github.com/sushanttusharjoshi/predictive-care/blob/main/frontend/lib/api.ts) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js App<br/>ui shell"]
  node_frontend_nav["Navigation<br/>shared ui<br/>[Nav.tsx]"]
  node_frontend_api["API Client<br/>http client<br/>[api.ts]"]
  node_dashboard_pages["Dashboard<br/>workflow pages"]
  node_patient_pages["Patient Views<br/>workflow pages"]
  node_alerts_pages["Alerts<br/>workflow pages"]
  node_admin_pages["Admin<br/>privileged views"]
end

subgraph group_backend["Backend API"]
  node_backend_main["FastAPI App<br/>service entrypoint<br/>[main.py]"]
  node_backend_main_pg["PG App<br/>async entrypoint<br/>[main_pg.py]"]
  node_auth_service["Auth<br/>security service<br/>[auth.py]"]
  node_hipaa_middleware["HIPAA Middleware<br/>compliance middleware<br/>[hipaa.py]"]
  node_audit_service["Audit Log<br/>compliance service<br/>[audit.py]"]
  node_patient_service["Patient Service<br/>domain service<br/>[create_patient.py]"]
  node_reminders_service["Reminders<br/>care workflow<br/>[reminders.py]"]
  node_trust_service["Trust Score<br/>ml workflow<br/>[trust_score.py]"]
  node_narratives_service["Narratives<br/>llm service<br/>[groq_narratives.py]"]
end

subgraph group_data_ml["Data / ML"]
  node_legacy_db[("Legacy DB<br/>storage adapter<br/>[database.py]")]
  node_pg_models[("PG Models<br/>orm schema<br/>[models_pg.py]")]
  node_pg_db[("Postgres DB<br/>async storage<br/>[database_pg.py]")]
  node_synthetic_data["Synthetic Data<br/>bootstrap pipeline"]
  node_ml_train["Training<br/>ml pipeline<br/>[train.py]"]
  node_ml_train_pg["PG Training<br/>ml pipeline<br/>[train_pg.py]"]
  node_ml_similar["Similar Patients<br/>inference module"]
end

subgraph group_external["External Services"]
  node_postgres[("PostgreSQL<br/>database")]
  node_groq(("Groq API<br/>llm api"))
end

node_frontend_app -->|"uses"| node_frontend_nav
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"renders"| node_dashboard_pages
node_frontend_app -->|"renders"| node_patient_pages
node_frontend_app -->|"renders"| node_alerts_pages
node_frontend_app -->|"renders"| node_admin_pages
node_frontend_api -->|"HTTP"| node_backend_main
node_frontend_api -->|"HTTP"| node_backend_main_pg
node_backend_main -->|"auth"| node_auth_service
node_backend_main -->|"audits"| node_hipaa_middleware
node_hipaa_middleware -->|"records"| node_audit_service
node_backend_main -->|"domain"| node_patient_service
node_backend_main -->|"domain"| node_reminders_service
node_backend_main -->|"scores"| node_trust_service
node_backend_main -->|"explains"| node_narratives_service
node_backend_main -->|"reads/writes"| node_legacy_db
node_backend_main_pg -->|"reads/writes"| node_pg_db
node_pg_db -->|"maps"| node_pg_models
node_pg_db -->|"connects"| node_postgres
node_legacy_db -.->|"optional"| node_postgres
node_synthetic_data -->|"loads"| node_postgres
node_ml_train -->|"trains on"| node_legacy_db
node_ml_train_pg -->|"trains on"| node_pg_db
node_ml_similar -->|"queries"| node_pg_db
node_narratives_service -->|"calls"| node_groq
node_backend_main -->|"stores"| node_postgres

click node_frontend_app "https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app"
click node_frontend_nav "https://github.com/sushanttusharjoshi/predictive-care/blob/main/frontend/components/Nav.tsx"
click node_frontend_api "https://github.com/sushanttusharjoshi/predictive-care/blob/main/frontend/lib/api.ts"
click node_dashboard_pages "https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/dashboard"
click node_patient_pages "https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/dashboard/patients"
click node_alerts_pages "https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/alerts"
click node_admin_pages "https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/admin"
click node_backend_main "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/main.py"
click node_backend_main_pg "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/main_pg.py"
click node_auth_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/auth.py"
click node_hipaa_middleware "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/middleware/hipaa.py"
click node_audit_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/audit.py"
click node_patient_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/create_patient.py"
click node_reminders_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/reminders.py"
click node_trust_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/trust_score.py"
click node_narratives_service "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/groq_narratives.py"
click node_legacy_db "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/database.py"
click node_pg_models "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/models_pg.py"
click node_pg_db "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/database_pg.py"
click node_synthetic_data "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/generate_synthetic.py"
click node_ml_train "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/train.py"
click node_ml_train_pg "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/train_pg.py"
click node_ml_similar "https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/similar_patients.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_nav,node_frontend_api,node_dashboard_pages,node_patient_pages,node_alerts_pages,node_admin_pages toneBlue
class node_backend_main,node_backend_main_pg,node_auth_service,node_hipaa_middleware,node_audit_service,node_patient_service,node_reminders_service,node_trust_service,node_narratives_service toneAmber
class node_legacy_db,node_pg_models,node_pg_db,node_synthetic_data,node_ml_train,node_ml_train_pg,node_ml_similar toneMint
class node_postgres,node_groq toneRose
```

## Components

### Frontend

Next.js presentation layer and UI workflows

- [Next.js App](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app): ui shell · App Router entry and page composition for the client experience · `frontend/app`
- [Navigation](https://github.com/sushanttusharjoshi/predictive-care/blob/main/frontend/components/Nav.tsx): shared ui · Shared navigation and cross-page layout controls · `frontend/components/Nav.tsx`
- [API Client](https://github.com/sushanttusharjoshi/predictive-care/blob/main/frontend/lib/api.ts): http client · Centralized backend API calls used by the UI · `frontend/lib/api.ts`
- [Dashboard](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/dashboard): workflow pages · Operational views for monitoring patients and model outputs · `frontend/app/dashboard`
- [Patient Views](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/dashboard/patients): workflow pages · Patient list and patient drill-down screens · `frontend/app/dashboard/patients`
- [Alerts](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/alerts): workflow pages · Reminders and exception handling views · `frontend/app/alerts`
- [Admin](https://github.com/sushanttusharjoshi/predictive-care/tree/main/frontend/app/admin): privileged views · Compliance and operations-facing screens · `frontend/app/admin`

### Backend API

FastAPI service with domain logic, auth, compliance, and ML

- [FastAPI App](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/main.py): service entrypoint · Primary backend entrypoint for the REST API · `backend/app/main.py`
- [PG App](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/main_pg.py): async entrypoint · PostgreSQL-oriented backend entrypoint · `backend/app/main_pg.py`
- [Auth](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/auth.py): security service · Authentication and role-based access control · `backend/app/services/auth.py`
- [HIPAA Middleware](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/middleware/hipaa.py): compliance middleware · Request-time PHI auditing and compliance logging · `backend/app/middleware/hipaa.py`
- [Audit Log](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/audit.py): compliance service · Persistent compliance and activity audit recording · `backend/app/services/audit.py`
- [Patient Service](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/create_patient.py): domain service · Patient creation and clinical workflow coordination · `backend/app/services/create_patient.py`
- [Reminders](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/reminders.py): care workflow · Medication reminders and adherence workflows · `backend/app/services/reminders.py`
- [Trust Score](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/trust_score.py): ml workflow · Adherence and risk scoring support for care workflows · `backend/app/services/trust_score.py`
- [Narratives](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/services/groq_narratives.py): llm service · Groq-backed natural-language explanation generation · `backend/app/services/groq_narratives.py`

### Data / ML

Persistence, dataset bootstrap, training, and inference support

- [Legacy DB](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/database.py): storage adapter · Non-PostgreSQL persistence path · `backend/app/data/database.py`
- [PG Models](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/models_pg.py): orm schema · PostgreSQL schema and ORM definitions · `backend/app/data/models_pg.py`
- [Postgres DB](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/database_pg.py): async storage · Async PostgreSQL data access layer · `backend/app/data/database_pg.py`
- [Synthetic Data](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/data/generate_synthetic.py): bootstrap pipeline · Synthetic patient generation and Synthea ingestion · `backend/app/data/generate_synthetic.py`
- [Training](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/train.py): ml pipeline · Model training for the legacy storage mode · `backend/app/ml/train.py`
- [PG Training](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/train_pg.py): ml pipeline · Model training for the PostgreSQL-backed mode · `backend/app/ml/train_pg.py`
- [Similar Patients](https://github.com/sushanttusharjoshi/predictive-care/blob/main/backend/app/ml/similar_patients.py): inference module · Patient similarity and cohort retrieval for recommendations · `backend/app/ml/similar_patients.py`

### External Services

Third-party and infrastructure dependencies

- **PostgreSQL**: database · Primary persistence backend for clinical and model data
- **Groq API**: llm api · External narrative generation service

## Connections

- Next.js App → Navigation: uses · Shared navigation is composed into the UI shell
- Next.js App → API Client: calls · Pages use the centralized API client
- Next.js App → Dashboard: renders · Dashboard workflow screens are part of the app router
- Next.js App → Patient Views: renders · Patient detail views are part of the app router
- Next.js App → Alerts: renders · Alerts workflow screens are part of the app router
- Next.js App → Admin: renders · Admin workflow screens are part of the app router
- API Client → FastAPI App: HTTP · Client requests go to the FastAPI backend
- API Client → PG App: HTTP · Some client flows target the PostgreSQL-oriented backend
- FastAPI App → Auth: auth · Primary API gates access through authentication
- FastAPI App → HIPAA Middleware: audits · Requests pass through HIPAA compliance logging
- HIPAA Middleware → Audit Log: records · Compliance middleware writes audit events
- FastAPI App → Patient Service: domain · Patient and workflow endpoints delegate to domain services
- FastAPI App → Reminders: domain · Reminder endpoints use care workflow service logic
- FastAPI App → Trust Score: scores · Risk and adherence scoring is surfaced through the API
- FastAPI App → Narratives: explains · API endpoints request natural-language explanations
- FastAPI App → Legacy DB: reads/writes · Legacy runtime uses the non-PG storage adapter
- PG App → Postgres DB: reads/writes · PG runtime uses the async PostgreSQL adapter
- Postgres DB → PG Models: maps · ORM/schema definitions shape persisted records
- Postgres DB → PostgreSQL: connects · Async data access targets PostgreSQL
- Legacy DB → PostgreSQL: optional · Local development can still persist to PostgreSQL-backed infrastructure
- Synthetic Data → PostgreSQL: loads · Bootstrap pipelines populate clinical data stores
- Training → Legacy DB: trains on · Legacy training reads from the non-PG data layer
- PG Training → Postgres DB: trains on · PG training reads from the async PostgreSQL data layer
- Similar Patients → Postgres DB: queries · Similarity retrieval uses persisted patient data
- Narratives → Groq API: calls · Narrative generation is delegated to Groq
- FastAPI App → PostgreSQL: stores · Primary backend persists clinical and audit data