Healthcare Revenue Cycle Command Center

Synthetic data only — no PHI. Every patient, provider, facility, and payer record is programmatically generated. All organization names are fictional and all NPIs are fake. This is a portfolio project, not a real healthcare deployment.

Tech stack by layer

Healthcare organizations lose revenue when claims are denied, delayed, unpaid, or not followed up in time. The money doesn't disappear in one dramatic moment — it leaks $4,000 at a time: a denial nobody works, an appeal window that quietly expires, a payer whose denial rate drifts up for months before anyone notices.

This system helps teams find where money is stuck, understand why, and decide which claims to work first. It answers the questions a revenue cycle team asks every day:

• Which claims were denied, and why?
• Which payers deny the most, and which need escalation?
• How much revenue is at risk right now?
• Which claims are aging past 30 / 60 / 90 days?
• Which claims should the team follow up on first?
• Are denial rates trending better or worse?
• How much was recovered after appeals and follow-up?

• Tracks claims, denials, payments, payer performance, and A/R aging in one governed model
• Calculates executive and operational KPIs (denial rate, revenue at risk, A/R over 90, appeal recovery)
• Automates follow-up tasks and payer alerts from transparent business rules
• Scores every claim 0–100 with an explainable, rule-based priority model
• Estimates potential recovery from working the top-priority claims first
• Presents insights through a FastAPI backend, a React dashboard, and a 5-page Power BI executive dashboard

Synthetic dataset (seed 42 — every run reproduces the same data):

Plus month-end A/R snapshots per open claim and rule-based follow-up tasks. Produced by the deterministic generator at etl/generate_synthetic_data.py.

flowchart LR
    A["Synthetic Data<br/>Generator"] --> B["Python ETL"]
    B --> C["Validation<br/>Suite"]
    C --> D[("Star Schema /<br/>CSV Tables")]
    D --> E["Automation<br/>Rules Engine"]
    E --> F["FastAPI<br/>Backend"]
    F --> G["React<br/>Dashboard"]
    D --> H["Power BI<br/>Reporting Layer"]

    classDef gen fill:#0B2545,stroke:#0B2545,color:#ffffff;
    classDef proc fill:#1D5BD6,stroke:#1D5BD6,color:#ffffff;
    classDef store fill:#0E8F7E,stroke:#0E8F7E,color:#ffffff;
    classDef serve fill:#06B6D4,stroke:#06B6D4,color:#083344;
    classDef bi fill:#475569,stroke:#475569,color:#ffffff;
    class A gen;
    class B,C,E proc;
    class D store;
    class F,G serve;
    class H bi;

Flow: Synthetic Data → Python ETL → Validation → Star Schema / CSV Tables → Automation Rules → FastAPI → React Dashboard → Power BI Layer.

CSV-first is deliberate: the whole system runs with pip install + npm install — no database required. The identical schema also exists as PostgreSQL DDL with keys, checks, and indexes. Full details: docs/architecture_diagram.md · docs/data_model_diagram.md · docs/process_flow.md.

Two features push this past a reporting dashboard into decision support. Both are rule-based and fully transparent — not a black-box ML model — which matters when staff must justify why a claim was worked.

In plain terms: the system gives each claim a 0–100 score and shows exactly why the claim is urgent.

Each claim also gets a tier — Critical / High / Medium / Low / Monitor — plus an ordered list of the business reasons behind the number. Points accrue from high-value denials, A/R aging, payer denial risk, appeal-deadline urgency, denial category, and open financial exposure. The full point schedule lives in one reusable module: automation/priority_scoring.py.

Priority Score: 100 / 100        Tier: Critical
─────────────────────────────────────────────────
  High-value denial above $5,000 ............ +30
  Appeal window at risk (denied 20+ days) ... +20
  Aged 61–90 days with an open balance ...... +18
  Payer denial rate above 20% ............... +15
  Open exposure above $10,000 ............... +15
  Missing-documentation denial .............. +8
─────────────────────────────────────────────────
  Raw total 106  →  capped at 100

In plain terms: the system estimates how much revenue could be recovered if the team works the top 25, 50, or 100 priority claims.

Pick a claim count and a recovery-rate assumption (30% / 40% / 50%); it ranks open claims by priority score, sums a de-duplicated at-risk base (denied + outstanding, without double-counting), and returns the estimated recoverable revenue, the tier workload, and the top recovery drivers. The recovery rate is an explicit planning assumption applied to at-risk balances — a decision aid, not a guaranteed collection.

Command Center	Claims Work Queue
Claim Detail	Payer Performance

All screenshots are captured from the running React app against the live API — none are mockups. More views (follow-up tasks, data dictionary) in powerbi/screenshots/.

The Power BI dashboard provides an executive reporting layer focused on revenue cycle performance, denial root causes, A/R aging, payer performance, and recovery opportunity.

1 Executive Overview	2 Denial Analysis
3 A/R Aging	4 Payer Performance
5 Work Queue & Recovery	Power BI Artifact The Power BI file is included at powerbi/Healthcare_Revenue_Cycle_Command_Center.pbix.

Automation rules (full spec: automation/alert_rules.md):

Data model — star schema with conformed dimensions. Dimensions: dim_patient, dim_provider, dim_facility, dim_payer, dim_denial_reason, dim_service_line, dim_date. Facts: fact_claims, fact_denials, fact_payments, fact_ar_snapshot, fact_followup_tasks. Full column reference: database/data_dictionary.md.

Full list with SQL: analytics/kpi_queries.sql. Every KPI is defined once and mirrored across SQL, the API, and DAX.

Prerequisites: Python 3.11+, Node 18+. PostgreSQL/Docker optional — everything runs in CSV mode.

1 · Backend / data setup

python -m pip install -r requirements.txt
python etl/run_pipeline.py                    # generate synthetic dataset
python etl/validate_data.py                   # 46 data-quality checks
python automation/generate_followup_tasks.py  # follow-up tasks + alerts

2 · API — http://localhost:8000 (Swagger UI at /docs)

python -m pip install -r api/requirements.txt
uvicorn api.main:app --reload

3 · Frontend — http://localhost:5173

cd frontend
npm install
npm run dev

4 · Optional PostgreSQL

docker compose up -d          # PostgreSQL 16 on localhost:5432
python etl/load_to_postgres.py

Shortcuts via Makefile: make pipeline, make validate, make api, make frontend.

The application is live on Render, deployed from the committed Blueprint at render.yaml as two services:

Live URLs

PostgreSQL is optional and is not required for the portfolio deployment — the API runs in CSV mode.

Hosted request flow

Browser  →  Render Static Site  →  FastAPI Web Service  →  In-memory synthetic CSV dataset
             (VITE_API_URL              (CSV mode default,       (built by etl/run_pipeline.py
              baked at build)            CORS from FRONTEND_URL)   during the backend deploy)

Environment variables — enter once in the Render dashboard on first Blueprint sync

Render may append a hostname suffix if a service name is already claimed. In the current deployment both services took the predicted names above; if you fork and redeploy, update both variables to whatever Render actually assigns.

Free-tier note: the backend Web Service may spin down when idle. The first request after inactivity is slower while the service wakes up; subsequent requests are fast. The frontend already shows a public-friendly "temporarily unavailable — please try again in a moment" message during that window — this does not indicate a broken deployment.

Full procedure, environment-variable reference, and troubleshooting (CORS errors, missing CSVs, cold starts, direct-route 404s): docs/deployment.md.

A complete, runnable revenue cycle analytics system:

• Working synthetic dataset — 6,000 claims across 9 payers with full denial/appeal lifecycles
• Validated data pipeline — 46-check suite gating referential integrity and financial reconciliation
• 12 API endpoints — KPIs, claims, payers, tasks, priority insights, recovery simulator
• React dashboard — six operational and executive views
• Automation — rule-generated, SLA-dated follow-up tasks and payer alerts
• Explainable priority scoring — transparent 0–100 score with per-claim drivers
• Revenue recovery simulator — recovery estimates from the top-priority queue
• Power BI executive dashboard — 5-page .pbix and production-ready DAX measures

In a real deployment, a system like this would let a revenue cycle team:

• Stop high-value leakage — catch large denials the day they post instead of weeks later
• Never miss an appeal window — deadline alerts convert silent write-offs into dated work
• Focus scarce staff — a priority-ranked queue replaces spreadsheet triage
• Hold payers accountable — denial-rate and payment-speed scorecards back the escalation conversation
• Plan recovery targets — size the payoff of a focused work sprint before committing staff

• Predictive denial-risk scoring on claim attributes before submission
• Write-back workflow (assign, note, close tasks from the UI)
• dbt transformation layer with tests and lineage
• 835/837 EDI ingestion for realistic sourcing
• Role-based access, audit logging, and facility-level row security

Case Study · Architecture · Data Model · Process Flow · Demo Script · Deployment Guide · Data Dictionary

This project uses synthetic / public-style healthcare data only and does not contain real patient information. All patient, provider, facility, and payer records are programmatically generated, all organization names are fictional, and all NPI numbers are fake. It is a portfolio and educational project — not a real healthcare deployment and not medical, billing, or financial advice.