# databricks-industry-solutions/medicare-risk-adjustment architecture

> Architecture diagram of the GitHub repository databricks-industry-solutions/medicare-risk-adjustment, 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/databricks-industry-solutions/medicare-risk-adjustment
- Repository: https://github.com/databricks-industry-solutions/medicare-risk-adjustment

## Overview

This repository is a Databricks solution accelerator for extracting Medicare HCC evidence from clinical notes and calculating patient RAF risk scores. Its principal workflow infers diagnosis codes and demographics, filters and organizes HCC evidence, combines it with patient status, and writes risk-score outputs. The sampled implementation is concentrated in one notebook; README describes the broader risk-adjustment purpose, while omitted notebook sections leave some intermediate wiring uncertain.

Main entry points: [`01-medicare-risk-adjustment.py`](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py) (Notebook workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clinical["Clinical NLP"]
  node_analysis["Notebook workflow"]
  node_disease["Disease extraction"]
  node_icd["ICD-10 resolution"]
  node_hcc["HCC status"]
end

subgraph group_patient["Patient Inference"]
  node_age["Age inference"]
  node_gender["Gender inference"]
  node_status["Patient status"]
  node_patientdata["Patient records"]
end

subgraph group_risk["Risk Adjustment"]
  node_raf["RAF calculation"]
  node_profile["Risk profile"]
end

subgraph group_data["Data Outputs"]
  node_delta[("Delta tables")]
  node_silver["HCC status output"]
  node_gold["Patient risk output"]
end

node_notes["Clinical notes"]
node_models["Clinical NLP models"]

node_notes -->|"provides notes"| node_analysis
node_analysis -->|"extracts diseases"| node_disease
node_disease -->|"resolves codes"| node_icd
node_analysis -.->|"uses pretrained models"| node_models
node_icd -->|"derives HCC status"| node_hcc
node_analysis -->|"infers age"| node_age
node_analysis -->|"infers gender"| node_gender
node_analysis -->|"creates mock status"| node_status
node_analysis -->|"groups patient data"| node_patientdata
node_hcc -->|"writes silver data"| node_delta
node_delta -->|"stores HCC status"| node_silver
node_analysis -->|"calculates scores"| node_raf
node_age -->|"supplies age"| node_raf
node_gender -->|"supplies gender"| node_raf
node_status -->|"supplies status"| node_raf
node_patientdata -->|"supplies diagnoses"| node_raf
node_raf -->|"produces risk scores"| node_profile
node_profile -->|"writes gold data"| node_delta
node_delta -->|"stores risk scores"| node_gold

click node_analysis "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_disease "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_icd "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_hcc "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_age "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_gender "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_status "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_patientdata "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_raf "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_profile "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_silver "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"
click node_gold "https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py"

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_analysis,node_disease,node_icd,node_hcc toneBlue
class node_age,node_gender,node_status,node_patientdata toneAmber
class node_raf,node_profile toneMint
class node_delta,node_silver,node_gold toneRose
class node_notes,node_models toneIndigo
```

## Components

### Clinical NLP

- [Notebook workflow](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Disease extraction](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [ICD-10 resolution](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [HCC status](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`

### Patient Inference

- [Age inference](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Gender inference](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Patient status](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Patient records](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`

### Risk Adjustment

- [RAF calculation](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Risk profile](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`

### Data Outputs

- **Delta tables**
- [HCC status output](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`
- [Patient risk output](https://github.com/databricks-industry-solutions/medicare-risk-adjustment/blob/main/01-medicare-risk-adjustment.py): `01-medicare-risk-adjustment.py`

### Other components

- **Clinical notes**
- **Clinical NLP models**

## Connections

- Clinical notes → Notebook workflow: provides notes
- Notebook workflow → Disease extraction: extracts diseases
- Disease extraction → ICD-10 resolution: resolves codes
- Notebook workflow → Clinical NLP models: uses pretrained models
- ICD-10 resolution → HCC status: derives HCC status
- Notebook workflow → Age inference: infers age
- Notebook workflow → Gender inference: infers gender
- Notebook workflow → Patient status: creates mock status
- Notebook workflow → Patient records: groups patient data
- HCC status → Delta tables: writes silver data
- Delta tables → HCC status output: stores HCC status
- Notebook workflow → RAF calculation: calculates scores
- Age inference → RAF calculation: supplies age
- Gender inference → RAF calculation: supplies gender
- Patient status → RAF calculation: supplies status
- Patient records → RAF calculation: supplies diagnoses
- RAF calculation → Risk profile: produces risk scores
- Risk profile → Delta tables: writes gold data
- Delta tables → Patient risk output: stores risk scores