# thrinesh13/medicare-claims-processing-analytics architecture

> Architecture diagram of the GitHub repository thrinesh13/medicare-claims-processing-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thrinesh13/medicare-claims-processing-analytics
- Repository: https://github.com/thrinesh13/medicare-claims-processing-analytics

## Overview

This repository is an analytical prototype for evaluating Medicare Part B claim straight-through processing, not an operational claims adjudication service. Its workflow generates synthetic claim lifecycle data, derives time-available features in PostgreSQL, scores claims and compares manual, checks-only, and checks-plus-score policies by accuracy and decision cost. The README also documents calibration, validation, sensitivity, and reporting analyses. The graph follows the pipeline and sampled Python/SQL responsibilities; data files referenced by source but absent from the supplied tree are not represented as repository nodes.

Main entry points: [`src/evaluate.py`](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/evaluate.py) (Scoring and policies), [`src/database.py`](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/database.py) (Database access), [`notebooks/02_decision_economics.ipynb`](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/notebooks/02_decision_economics.ipynb) (Decision economics analysis), [`scripts/run_pipeline.py`](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/scripts/run_pipeline.py) (Pipeline entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_claims["Claim Data"]
  node_fetch["CMS source retrieval<br/>[fetch_sources.py]"]
  node_generator["Claim lifecycle generator<br/>[generate.py]"]
  node_pipeline["Pipeline entry point<br/>[run_pipeline.py]"]
end

subgraph group_features["Feature Engineering"]
  node_database["Database access<br/>[database.py]"]
  node_schema["Claims schema<br/>[01_schema.sql]"]
  node_feature_sql["As-of features<br/>[02_features.sql]"]
end

subgraph group_decisions["Policy Evaluation"]
  node_evaluator["Scoring and policies<br/>[evaluate.py]"]
  node_model["Fitted model<br/>[model.joblib]"]
end

subgraph group_reporting["Economics &amp; Analysis"]
  node_report_sql["Decision reporting<br/>[03_reporting.sql]"]
  node_policy_results["Policy summaries<br/>[policy_summary.csv]"]
  node_sensitivity["Cost sensitivity<br/>[sensitivity.csv]"]
  node_calibration["Calibration results<br/>[calibration.csv]"]
  node_monthly["Monthly results<br/>[monthly.csv]"]
  node_segments["Segment results<br/>[segments.csv]"]
  node_facts["Claim decisions<br/>[fact_decisions.csv]"]
  node_notebook_data["Data and SQL analysis"]
  node_notebook_economics["Decision economics analysis"]
end

node_analyst(("Analyst"))
node_cms[("CMS data")]
node_postgres[("PostgreSQL")]

node_fetch -->|"requests data"| node_cms
node_pipeline -->|"calls"| node_generator
node_pipeline -->|"loads and features"| node_database
node_pipeline -->|"runs evaluation"| node_evaluator
node_generator -.->|"uses benchmarks"| node_fetch
node_database -->|"executes"| node_schema
node_database -->|"loads claims"| node_postgres
node_database -->|"executes features"| node_feature_sql
node_feature_sql -->|"queries history"| node_postgres
node_database -->|"returns features"| node_evaluator
node_evaluator -->|"saves"| node_model
node_evaluator -->|"writes"| node_policy_results
node_evaluator -->|"writes"| node_sensitivity
node_evaluator -->|"writes"| node_calibration
node_evaluator -->|"writes"| node_monthly
node_evaluator -->|"writes"| node_segments
node_evaluator -->|"writes"| node_facts
node_database -->|"executes reporting"| node_report_sql
node_database -->|"loads decisions"| node_facts
node_report_sql -->|"creates reporting table"| node_postgres
node_analyst -->|"explores"| node_notebook_data
node_analyst -->|"evaluates results"| node_notebook_economics
node_notebook_data -->|"queries features"| node_postgres
node_notebook_economics -->|"reads"| node_policy_results
node_notebook_economics -->|"reads"| node_sensitivity
node_notebook_economics -->|"reads"| node_calibration
node_notebook_economics -->|"reads"| node_monthly
node_notebook_economics -->|"reads"| node_segments

click node_fetch "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/scripts/fetch_sources.py"
click node_generator "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/generate.py"
click node_pipeline "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/scripts/run_pipeline.py"
click node_database "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/database.py"
click node_schema "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/01_schema.sql"
click node_feature_sql "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/02_features.sql"
click node_evaluator "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/evaluate.py"
click node_report_sql "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/03_reporting.sql"
click node_policy_results "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/policy_summary.csv"
click node_sensitivity "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/sensitivity.csv"
click node_calibration "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/calibration.csv"
click node_monthly "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/monthly.csv"
click node_segments "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/segments.csv"
click node_facts "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/fact_decisions.csv"
click node_model "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/model.joblib"
click node_notebook_data "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/notebooks/01_data_and_sql.ipynb"
click node_notebook_economics "https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/notebooks/02_decision_economics.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fetch,node_generator,node_pipeline toneBlue
class node_database,node_schema,node_feature_sql,node_cms,node_postgres toneAmber
class node_evaluator,node_model toneMint
class node_report_sql,node_policy_results,node_sensitivity,node_calibration,node_monthly,node_segments,node_facts,node_notebook_data,node_notebook_economics toneRose
class node_analyst toneIndigo
```

## Components

### Claim Data

- [CMS source retrieval](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/scripts/fetch_sources.py): `scripts/fetch_sources.py`
- [Claim lifecycle generator](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/generate.py): `src/generate.py`
- [Pipeline entry point](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/scripts/run_pipeline.py): `scripts/run_pipeline.py`

### Feature Engineering

- [Database access](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/database.py): `src/database.py`
- [Claims schema](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/01_schema.sql): `sql/01_schema.sql`
- [As-of features](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/02_features.sql): `sql/02_features.sql`

### Policy Evaluation

- [Scoring and policies](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/src/evaluate.py): `src/evaluate.py`
- [Fitted model](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/model.joblib): `results/model.joblib`

### Economics & Analysis

- [Decision reporting](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/sql/03_reporting.sql): `sql/03_reporting.sql`
- [Policy summaries](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/policy_summary.csv): `results/policy_summary.csv`
- [Cost sensitivity](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/sensitivity.csv): `results/sensitivity.csv`
- [Calibration results](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/calibration.csv): `results/calibration.csv`
- [Monthly results](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/monthly.csv): `results/monthly.csv`
- [Segment results](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/segments.csv): `results/segments.csv`
- [Claim decisions](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/results/fact_decisions.csv): `results/fact_decisions.csv`
- [Data and SQL analysis](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/notebooks/01_data_and_sql.ipynb): `notebooks/01_data_and_sql.ipynb`
- [Decision economics analysis](https://github.com/thrinesh13/medicare-claims-processing-analytics/blob/main/notebooks/02_decision_economics.ipynb): `notebooks/02_decision_economics.ipynb`

### Other components

- **Analyst**
- **CMS data**
- **PostgreSQL**

## Connections

- CMS source retrieval → CMS data: requests data
- Pipeline entry point → Claim lifecycle generator: calls
- Pipeline entry point → Database access: loads and features
- Pipeline entry point → Scoring and policies: runs evaluation
- Claim lifecycle generator → CMS source retrieval: uses benchmarks
- Database access → Claims schema: executes
- Database access → PostgreSQL: loads claims
- Database access → As-of features: executes features
- As-of features → PostgreSQL: queries history
- Database access → Scoring and policies: returns features
- Scoring and policies → Fitted model: saves
- Scoring and policies → Policy summaries: writes
- Scoring and policies → Cost sensitivity: writes
- Scoring and policies → Calibration results: writes
- Scoring and policies → Monthly results: writes
- Scoring and policies → Segment results: writes
- Scoring and policies → Claim decisions: writes
- Database access → Decision reporting: executes reporting
- Database access → Claim decisions: loads decisions
- Decision reporting → PostgreSQL: creates reporting table
- Analyst → Data and SQL analysis: explores
- Analyst → Decision economics analysis: evaluates results
- Data and SQL analysis → PostgreSQL: queries features
- Decision economics analysis → Policy summaries: reads
- Decision economics analysis → Cost sensitivity: reads
- Decision economics analysis → Calibration results: reads
- Decision economics analysis → Monthly results: reads
- Decision economics analysis → Segment results: reads