# villegasjv55/medicaid-access-monitor architecture

> Architecture diagram of the GitHub repository villegasjv55/medicaid-access-monitor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/villegasjv55/medicaid-access-monitor
- Repository: https://github.com/villegasjv55/medicaid-access-monitor

## Overview

Medicaid Access Monitor turns public CMS data into validated monthly tables, analytical views, and operational recommendations. The principal user workflow is opening the Streamlit dashboard to explore national access, state rankings, Florida, and state comparisons. Separate deliverables include Excel reporting, a DuckDB query pack, a findings memo, and an explicitly simulated rollout plan. The README documents these capabilities; source excerpts confirm the cleaning outputs, dashboard data reads, and SQL runner inputs and outputs. Other workbook and document internals were not sampled.

Main entry points: [`data/clean`](https://github.com/villegasjv55/medicaid-access-monitor/tree/main/data/clean) (Clean Monthly Tables), [`python/clean_data.py`](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/clean_data.py) (Cleaning Pipeline), [`dashboard/app.py`](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/dashboard/app.py) (Interactive Dashboard), [`python/run_sql.py`](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/run_sql.py) (SQL Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["CMS Data"]
  node_caa["CAA Metrics"]
  node_pi["PI Dataset"]
end

subgraph group_analysis["Data Processing"]
  node_cleaner["Cleaning Pipeline<br/>[clean_data.py]"]
  node_clean_tables["Clean Monthly Tables"]
  node_quality["Quality and Reconciliation<br/>[clean_data.py]"]
  node_lookup["State Lookup<br/>[lookup_states.csv]"]
end

subgraph group_products["Access Reporting"]
  node_dashboard["Interactive Dashboard<br/>[app.py]"]
  node_excel["Excel Reporting"]
  node_sql_runner["SQL Runner<br/>[run_sql.py]"]
  node_queries["DuckDB Query Pack<br/>[queries.sql]"]
  node_sql_results["Query Results"]
end

subgraph group_actions["Operational Planning"]
  node_memo["Findings Memo<br/>[findings_memo.md]"]
  node_simulation["Rollout Simulation<br/>[rollout_plan.md]"]
  node_briefing["Executive Briefing"]
end

node_analyst(("Analyst"))

node_analyst -->|"explores access"| node_dashboard
node_caa -->|"reads source"| node_cleaner
node_pi -->|"reads source"| node_cleaner
node_cleaner -->|"writes tables"| node_clean_tables
node_cleaner -->|"checks and reconciles"| node_quality
node_clean_tables -->|"loads and joins"| node_dashboard
node_lookup -->|"joins state details"| node_dashboard
node_clean_tables -->|"loads CSV views"| node_sql_runner
node_lookup -->|"loads CSV view"| node_sql_runner
node_queries -->|"runs queries"| node_sql_runner
node_sql_runner -->|"writes results"| node_sql_results
node_clean_tables -->|"reports on data"| node_excel
node_dashboard -->|"shows comparisons"| node_analyst
node_excel -->|"presents reporting"| node_analyst
node_sql_results -->|"provides query results"| node_analyst
node_memo -->|"communicates findings"| node_analyst
node_simulation -->|"plans pilot"| node_analyst
node_briefing -->|"summarizes results"| node_analyst

click node_caa "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/raw/medicaid-chip-caa-reporting-metrics-long-table-october-2024-release.csv"
click node_pi "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/raw/pi-dataset-march-2026release.csv"
click node_cleaner "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/clean_data.py"
click node_clean_tables "https://github.com/villegasjv55/medicaid-access-monitor/tree/main/data/clean"
click node_quality "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/clean_data.py"
click node_lookup "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/lookup/lookup_states.csv"
click node_dashboard "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/dashboard/app.py"
click node_excel "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/excel/Medicaid_Access_Reporting.xlsx"
click node_sql_runner "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/run_sql.py"
click node_queries "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/sql/queries.sql"
click node_sql_results "https://github.com/villegasjv55/medicaid-access-monitor/tree/main/sql/results"
click node_memo "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/docs/findings_memo.md"
click node_simulation "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/simulation/rollout_plan.md"
click node_briefing "https://github.com/villegasjv55/medicaid-access-monitor/blob/main/presentation/executive_briefing.pdf"

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_caa,node_pi toneBlue
class node_cleaner,node_clean_tables,node_quality,node_lookup toneAmber
class node_dashboard,node_excel,node_sql_runner,node_queries,node_sql_results toneMint
class node_memo,node_simulation,node_briefing toneRose
class node_analyst toneIndigo
```

## Components

### CMS Data

- [CAA Metrics](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/raw/medicaid-chip-caa-reporting-metrics-long-table-october-2024-release.csv): `data/raw/medicaid-chip-caa-reporting-metrics-long-table-october-2024-release.csv`
- [PI Dataset](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/raw/pi-dataset-march-2026release.csv): `data/raw/pi-dataset-march-2026release.csv`

### Data Processing

- [Cleaning Pipeline](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/clean_data.py): `python/clean_data.py`
- [Clean Monthly Tables](https://github.com/villegasjv55/medicaid-access-monitor/tree/main/data/clean): `data/clean`
- [Quality and Reconciliation](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/clean_data.py): `python/clean_data.py`
- [State Lookup](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/data/lookup/lookup_states.csv): `data/lookup/lookup_states.csv`

### Access Reporting

- [Interactive Dashboard](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/dashboard/app.py): `dashboard/app.py`
- [Excel Reporting](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/excel/Medicaid_Access_Reporting.xlsx): `excel/Medicaid_Access_Reporting.xlsx`
- [SQL Runner](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/python/run_sql.py): `python/run_sql.py`
- [DuckDB Query Pack](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/sql/queries.sql): `sql/queries.sql`
- [Query Results](https://github.com/villegasjv55/medicaid-access-monitor/tree/main/sql/results): `sql/results`

### Operational Planning

- [Findings Memo](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/docs/findings_memo.md): `docs/findings_memo.md`
- [Rollout Simulation](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/simulation/rollout_plan.md): `simulation/rollout_plan.md`
- [Executive Briefing](https://github.com/villegasjv55/medicaid-access-monitor/blob/main/presentation/executive_briefing.pdf): `presentation/executive_briefing.pdf`

### Other components

- **Analyst**

## Connections

- Analyst → Interactive Dashboard: explores access (evidence: `README.md`)
- CAA Metrics → Cleaning Pipeline: reads source (evidence: `README.md`)
- PI Dataset → Cleaning Pipeline: reads source (evidence: `README.md`)
- Cleaning Pipeline → Clean Monthly Tables: writes tables (evidence: `python/clean_data.py`)
- Cleaning Pipeline → Quality and Reconciliation: checks and reconciles (evidence: `README.md`)
- Clean Monthly Tables → Interactive Dashboard: loads and joins (evidence: `dashboard/app.py`)
- State Lookup → Interactive Dashboard: joins state details (evidence: `dashboard/app.py`)
- Clean Monthly Tables → SQL Runner: loads CSV views (evidence: `python/run_sql.py`)
- State Lookup → SQL Runner: loads CSV view (evidence: `python/run_sql.py`)
- DuckDB Query Pack → SQL Runner: runs queries (evidence: `python/run_sql.py`)
- SQL Runner → Query Results: writes results (evidence: `python/run_sql.py`)
- Clean Monthly Tables → Excel Reporting: reports on data (evidence: `README.md`)
- Interactive Dashboard → Analyst: shows comparisons (evidence: `README.md`)
- Excel Reporting → Analyst: presents reporting (evidence: `README.md`)
- Query Results → Analyst: provides query results (evidence: `README.md`)
- Findings Memo → Analyst: communicates findings (evidence: `README.md`)
- Rollout Simulation → Analyst: plans pilot (evidence: `README.md`)
- Executive Briefing → Analyst: summarizes results (evidence: `README.md`)