How sushanttusharjoshi/predictive-care works
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: main.py FastAPI App · app Next.js App · database_pg.py Postgres DB · api.ts API Client
Components 25
Frontend
Next.js presentation layer and UI workflows
- Next.js App · App Router entry and page composition for the client experience
frontend/app - Navigation · Shared navigation and cross-page layout controls
frontend/components/Nav.tsx - API Client · Centralized backend API calls used by the UI
frontend/lib/api.ts - Dashboard · Operational views for monitoring patients and model outputs
frontend/app/dashboard - Patient Views · Patient list and patient drill-down screens
frontend/app/dashboard/patients - Alerts · Reminders and exception handling views
frontend/app/alerts - Admin · Compliance and operations-facing screens
frontend/app/admin
Backend API
FastAPI service with domain logic, auth, compliance, and ML
- FastAPI App · Primary backend entrypoint for the REST API
backend/app/main.py - PG App · PostgreSQL-oriented backend entrypoint
backend/app/main_pg.py - Auth · Authentication and role-based access control
backend/app/services/auth.py - HIPAA Middleware · Request-time PHI auditing and compliance logging
backend/app/middleware/hipaa.py - Audit Log · Persistent compliance and activity audit recording
backend/app/services/audit.py - Patient Service · Patient creation and clinical workflow coordination
backend/app/services/create_patient.py - Reminders · Medication reminders and adherence workflows
backend/app/services/reminders.py - Trust Score · Adherence and risk scoring support for care workflows
backend/app/services/trust_score.py - Narratives · Groq-backed natural-language explanation generation
backend/app/services/groq_narratives.py
Data / ML
Persistence, dataset bootstrap, training, and inference support
- Legacy DB · Non-PostgreSQL persistence path
backend/app/data/database.py - PG Models · PostgreSQL schema and ORM definitions
backend/app/data/models_pg.py - Postgres DB · Async PostgreSQL data access layer
backend/app/data/database_pg.py - Synthetic Data · Synthetic patient generation and Synthea ingestion
backend/app/data/generate_synthetic.py - Training · Model training for the legacy storage mode
backend/app/ml/train.py - PG Training · Model training for the PostgreSQL-backed mode
backend/app/ml/train_pg.py - Similar Patients · Patient similarity and cohort retrieval for recommendations
backend/app/ml/similar_patients.py
External Services
Third-party and infrastructure dependencies
- PostgreSQL · Primary persistence backend for clinical and model data
- Groq API · External narrative generation service
Connections 26
- 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