EHR Risk Train path
POST /v1/jobs/train → background ThreadPool → training.train → poll GET /v1/jobs/{id}
Design & architecture diagrams
How the application is structured, how data moves through the system, and how you iterate (fine-tune) a research model. Drawn from the real code paths in this repository.
1. Big-picture architecture
Three entry surfaces (browser, CLI, OpenAPI) share one FastAPI + ML core. Artifacts live on the host filesystem.
2. End-to-end application data flow
Every research run follows the same pipeline. Numbers match the stages below.
1Ingest
Demo CSV, upload, form JSON, SQL, or map-import → data/uploads/
→
2Health
GET /v1/datasets/health blockers / warnings
→
3Task
YAML or Config: horizon, windows, split, model
→
4Features
Index truncate + w7d_/w30d_/w180d_
→
5Train
Fit ± calibrate → metrics + model.pkl
→
6Trust
Leakage audit, SHAP, fairness, Analytics
→
7Serve
POST /v1/predict + Predict UI
Raw EHR rowsDemo / upload / SQL CSV
Health gate
GET /v1/datasets/healthTask / configHorizon · windows · split
Feature tablePatient × windows (index-safe)
Train / compareSplit + fit ± calibrate
reports/ + runs/Metrics · plots · manifests
Predict / explainSchema features · SHAP
Ingest → health → task → features → train → trust artifacts → serve. Labels use post-index events only.
3. Temporal / feature design (why leakage matters)
Hard rule: features use only events at or before index_time. Labels use only events after index, inside the horizon.
Feature columns look like: w7d_glucose, w30d_visit_count, w180d_icd_unique_count
Prediction form uses THESE names — not raw EHR column names.
4. HTTP request path (UI → API → ML)
Example: user clicks Predict in the Angular workbench (Compose: nginx proxies /v1/* → api:8000; hosted demo calls ehr-api.larucare.com via baked API_ENDPOINT).
Browser
UI
UI
Angular workbench
POST /v1/predict with { features, include_explanation }
- Local Compose: same-origin via nginx on
:8080 - Split deploy: absolute
API_ENDPOINT(CORS required)
FastAPI
api/main.py · researcher routes
- Optional
X-API-KeywhenAPI_KEYis set - Load active artifact
model.pkl
ML core
inference.predict · explainability
- Align vector to
feature_columns predict_proba→risk_probability+risk_level- Optional SHAP drivers when requested / available
Response
JSON → Predict page charts
Research score only — not clinical advice.
Same stack serves train / audit / shap as background jobs (POST /v1/jobs/* → poll GET /v1/jobs/{id}).
Analytics path
GET /v1/datasets/profile?path=&age_band=&label= → KPIs, charts, cohort table
5. Training pipeline internals
1
data_path CSV
Longitudinal demo / BYO upload / processed extract (local).
2
Build feature matrix
Longitudinal multi-window (w7d_ / w30d_ / w180d_) or tabular schema.
3
Split
split_by_patient— group-aware (preferred for EHR)temporal_split— time-aware hold-out
4
Fit estimator
logreg · random_forest · xgboost · lightgbm
5
Optional isotonic calibration
CLI --calibrate / Train UI checkbox — improves Brier / ECE.
6
Evaluate hold-out
AUROC · PR-AUC · Brier · ECE (report honestly with split type).
7
Write artifacts
model.pklwhen promoted / single train promotereports/evaluation_report.jsonreports/feature_importance.jsonreports/calibration_holdout.pngreports/runs/<run_id>/
Training never uses post-index features; promote copies the chosen artifact to the active path for Predict.
6. Fine-tuning & model iteration (overview)
This framework does not fine-tune large language models. “Fine-tuning” here means iterating a tabular risk model: better data, windows, splits, model family, and calibration — then promoting the best artifact.
Full step-by-step guide: Fine-tuning playbook →
7. Runtime topology (Docker)
docker compose up --build- Train
model.pklif missing - Exits when ready
- FastAPI ·
ehr-risk-api - Repo mounted for
data/·reports/ - OpenAPI at
/docs
- Angular SPA + nginx
- Routes:
/Datasets Train Results Analytics Predict Config Docs /v1/*→api:8000/health·/api-docs→ Swagger
Hosted split deploy: UI at ehr-risk-framework.larucare.com, API at ehr-api.larucare.com (bake API_ENDPOINT + set CORS_ORIGINS).
8. Trust & serve loop
After every serious train
- Run leakage audit (Train page or API job)
- Check Brier / ECE; enable calibrate if needed
- Generate SHAP; inspect Analytics + Results
- Download results ZIP for your methods appendix
Before you demo Predict
- Confirm
GET /v1/model/schemamatches your features - Fill medians → predict → read SHAP drivers
- State clearly: research score, not clinical advice
Next: Fine-tuning playbook · Architecture notes · Commands