Real-time 30-day hospital readmission prevention. A production-shaped healthcare data-engineering platform that ingests FHIR R4 and HL7 v2 ADT feeds, builds a medallion lakehouse on Apache Iceberg, computes validated clinical risk (LACE index + Charlson Comorbidity Index), trains an XGBoost model that augments LACE, and serves a risk-at-discharge score as a FHIR RiskAssessment to a clinician worklist.
The whole pipeline runs end-to-end with zero infrastructure — one command, no Docker/Kafka/Spark. See Quickstart.
Medicare's Hospital Readmissions Reduction Program (HRRP) penalizes hospitals up to 3% of all inpatient Medicare reimbursement for excess 30-day readmissions. The penalized cohorts are:
| Cohort | Condition |
|---|---|
| AMI | Acute myocardial infarction |
| HF | Heart failure |
| COPD | Chronic obstructive pulmonary disease |
| PNEU | Pneumonia |
| CABG | Coronary artery bypass graft |
| THA/TKA | Elective hip / knee replacement |
Flagging high-risk patients at discharge — when a care manager can still act (follow-up call, med reconciliation, home health) — is a top revenue-cycle and quality priority. ReadmitGuard models exactly that decision point.
HL7 v2 ADT (A01/A03/A08) FHIR R4 Bundles
(MSH/EVN/PID/PV1) (Patient/Encounter/Condition/
│ Observation/MedicationRequest)
└───────────────┬─────────────────────┘
▼
┌─────────┐
│ Kafka │ fhir.bundles / hl7.adt
└────┬────┘
▼
┌──────────────────────────┐
│ Spark Structured Streaming│
└────────────┬─────────────┘
▼
┌──────────── Medallion Lakehouse (Apache Iceberg / MinIO) ───────────┐
│ BRONZE raw payloads (append-only) │
│ SILVER parsed + validated + HIPAA Safe-Harbor DE-IDENTIFIED + dedup│
│ GOLD readmission_features (LACE + Charlson, one row/discharge) │
└────────────┬───────────────────────────────────────────────────────┘
▼
┌────────────┐ ┌──────────────────────────┐
│ dbt │────▶│ XGBoost readmission model │
│ tests+freshness │ (LACE-augmented) │
└────────────┘ └──────────┬───────────────┘
▼
┌───────────────────┐ ┌─────────────────────────┐
│ FastAPI risk API │ │ Streamlit clinician │
│ → FHIR Risk- │ │ worklist (live census + │
│ Assessment │ │ ranked risk) │
└───────────────────┘ └─────────────────────────┘
Dagster orchestration • Prometheus / Grafana
LACE index (van Walraven et al., CMAJ 2010) — 0–19, predicts 30-day readmission or death:
| Component | Source |
|---|---|
| L — Length of stay | discharge − admit |
| A — Acuity of admission | emergency/urgent via ED → 3 pts |
| C — Charlson comorbidity | ICD-10 comorbidities |
| E — ED visits prior 6 months | prior-utilization rollup |
Charlson Comorbidity Index is computed from ICD-10-CM codes using standard Quan weights, with the usual hierarchy rules (complicated diabetes supersedes uncomplicated; metastatic supersedes localized malignancy; severe liver supersedes mild). The XGBoost model uses LACE, Charlson, and additional encounter features (age, prior utilization, disposition, HRRP cohort, med count) to refine the risk estimate beyond the LACE score alone.
Metrics below are the real output of make demo on the synthetic cohort —
not fabricated. They will reproduce exactly with the fixed seed.
| Metric | Value |
|---|---|
| Patients / encounters | 4,000 / 11,095 |
| Gold rows (index discharges) | 4,000 |
| 30-day readmission prevalence | 0.206 |
| AUROC | 0.699 |
| AUPRC | 0.368 (baseline = prevalence 0.206) |
| Brier score | 0.201 |
| Train / test split | 3,000 / 1,000 (stratified) |
An AUROC near 0.70 is in the honest range for LACE-style EHR readmission models on real data; the synthetic generator was tuned to produce learnable — not trivial — signal, and per-cohort rates track HRRP reality (HF/COPD highest, elective THA/TKA lowest).
make demo # creates venv, installs deps, runs the whole pipeline
# or:
python -m readmitguard.demoThis generates synthetic FHIR/HL7 → parses → de-identifies → builds the gold
feature mart (pandas + DuckDB) → trains XGBoost → evaluates → scores a sample
patient and prints a FHIR RiskAssessment. Artifacts land in data/.
make test # 24 unit tests (de-id, LACE/Charlson, parsing, model)
make smoke # demo + testsmake config # validate docker compose config
make up # Kafka, Spark, MinIO, Iceberg REST, Postgres, API,
# dashboard, Dagster, Prometheus, Grafana
make stream # stream synthetic FHIR/HL7 into Kafka
make dbt-run # dbt build (models + tests + freshness)
make downEndpoints: API :8000 · Dashboard :8501 · Dagster :3000 · Grafana :3001.
See docs/RUN_GUIDE.md.
| Layer | Technology |
|---|---|
| Standards | FHIR R4, HL7 v2.5 ADT, ICD-10-CM, LOINC, RxNorm |
| Streaming | Apache Kafka, Spark Structured Streaming |
| Lakehouse | Apache Iceberg on MinIO (S3), REST catalog |
| Transform | dbt (tests + freshness), DuckDB (dev) / Spark (prod) |
| ML | XGBoost, scikit-learn |
| Serving | FastAPI (FHIR RiskAssessment), Streamlit |
| Orchestration | Dagster (assets, schedules, lineage) |
| Observability | Prometheus, Grafana |
| Compliance | HIPAA Safe Harbor de-id, salted-hash tokenization, audit log |
readmitguard/
├── readmitguard/ # Python package
│ ├── datagen/ # Synthea-style FHIR + HL7 generator
│ ├── parsing/ # FHIR / HL7 parsers (fail-safe)
│ ├── deident/ # HIPAA Safe Harbor de-identification (+ tests)
│ ├── features/ # gold.readmission_features builder (LACE/Charlson)
│ ├── model/ # XGBoost train/eval + FHIR RiskAssessment scorer
│ ├── serving/ # FastAPI risk API (auth + rate limit + metrics)
│ ├── dashboard/ # Streamlit clinician worklist
│ ├── demo/ # zero-infra end-to-end entrypoint
│ ├── clinical.py # HRRP, ICD-10, Charlson, LOINC, RxNorm reference
│ └── lace.py # LACE index
├── spark/ # bronze ingest + silver transform (Iceberg)
├── dbt/readmitguard_dbt/ # dbt project (silver + gold, tests, freshness)
├── dagster_pipeline/ # asset graph + schedule
├── docker/ # Dockerfiles, Prometheus, Grafana
├── tests/ # pytest suite
├── docs/ # ARCHITECTURE, COMPLIANCE, RUN_GUIDE
├── docker-compose.yml
└── Makefile
All data in this project is 100% synthetic, generated with a fixed seed, and contains no real Protected Health Information. The generator emits realistic FHIR/HL7 structures and injects HRRP-correlated readmission patterns so the model learns real signal, but the patients do not exist. Clinical code mappings (ICD-10/Charlson/HRRP) are curated representative subsets, not exhaustive groupers. This software is decision-support scaffolding for portfolio/education purposes and is not a medical device — not for clinical use.
MIT © 2026 Koutilya Yenumula