System thesis
Case study
Hospital Readmission FHIR ML API
Synthetic FHIR scoring service that turns transition-of-care risk modeling into an inspectable API contract.
Primary evidence: age, utilization, comorbidity, medications, labs, discharge
At a glance
- Input contract
- Patient, Encounter, Condition, MedicationRequest, Observation, Procedure
- Output
- Risk probability, band, and top contributing features
- Runtime
- FastAPI, tests, Docker, model-card notes
Feature groupsage, utilization, comorbidity, medications, labs, discharge
Score surfaceprobability-like risk + low/medium/high band
Evidence assetssample JSON response, model card, architecture notes
System problem
Why this system exists.
Transition-of-care teams need risk signals that move through APIs, contracts, and review workflows instead of disconnected notebooks. This repo demonstrates that system shape with synthetic FHIR-style bundles.
Implementation surface
What was built.
- FastAPI endpoints.
- FHIR-style parser and feature builder.
- Transparent risk scorer.
- Synthetic examples, Docker packaging, CI, and model-card docs.
Architecture
A system map for the project.
Synthetic FHIR bundle -> schema validation -> parser -> feature builder -> risk scorer -> explanation payload -> FastAPI response -> tests and model-card documentation.
A standards-aware API path that keeps data contracts, feature extraction, scoring, explanations, and validation separate.
FHIR Contract
Synthetic bundleFastAPI schemaresource validation
Feature Layer
FHIR parserfeature builderrisk matrix
Model Layer
scorerfeature contributionsrisk band
Validation Layer
sample responsemodel cardpytest + Docker
How it works
Input, transformation, model or agent logic, and reviewable output.
FHIR bundle intake
The API starts from synthetic FHIR-style resources so the demo can show healthcare data contracts without patient data.
Feature matrix
The parser converts demographics, utilization, comorbidities, labs, and discharge context into a repeatable feature vector.
Explainable scoring
The response includes risk band and top contributors, which makes the output reviewable instead of a black-box score.
MLOps boundary
Tests, Docker, model-card text, and privacy docs communicate the intended production shape without claiming clinical validation.
Evidence
Screenshots, responses, diagrams, tests, and model tables from the source repos.
Artifacts are included only where the public repo has enough context to show them safely.
Sample high-risk API response
{
"model_version": "readmission-risk-demo-v0.1.0",
"readmission_risk_probability": 0.98,
"risk_band": "high",
"top_features": [
{ "feature": "prior_admissions_180d", "direction": "increases_risk" },
{ "feature": "comorbidity_count", "direction": "increases_risk" },
{ "feature": "age", "direction": "increases_risk" }
]
}Feature engineering matrix
Demographics, utilization, comorbidity burden, medications, abnormal labs, procedures, and discharge disposition feed the readmission feature contract.
Engineering Decisions
Synthetic data by design
The repo keeps the FHIR contract visible while avoiding PHI, claims data, or employer workflows.
API-first presentation
FastAPI endpoints make the model usable by downstream services and easy to verify with examples.
Transparent model stand-in
A deterministic scorer keeps the portfolio demo portable while preserving the feature contract a governed model would consume.
Validation / reliability
How the system is made reviewable.
- API, schema, feature extraction, and response contracts are covered by tests.
- Synthetic examples support repeatable local demonstrations.
- Public demo assumptions are separated from clinical deployment requirements.
- FastAPI health and metadata endpoints.
- Dockerfile and compose support local runtime verification.
- CI-oriented test and compile paths.
Limits / responsible use
Synthetic portfolio demo only. No PHI, PII, or clinical decision-support deployment is represented.
- Synthetic-only data keeps the FHIR contract visible without exposing PHI or employer workflows.
- The feature contract, response shape, tests, and model-card notes make the demo inspectable.
- Real clinical deployment would require validation, monitoring, governance, and workflow review beyond this public artifact.
Repository
Open the source repo and inspect the implementation boundary.
All public examples are synthetic, sanitized, historical, or research/demo implementations. No PHI, PII, employer-confidential data, proprietary claims data, private keys, production credentials, or sensitive datasets are included.