// 05 — us healthcare

US Healthcare for Technologists

How US healthcare works, for software and data people. 58 topics across the system and money flow, code sets, claims & eligibility data, dbt + Tuva modeling, risk adjustment (CMS-HCC, RAF), quality (HEDIS, Stars), compliance and ML.
Total
58
Done
0
Progress
0%
Left
58
Est. time
~43 h

US healthcare system & money flow

system 0/7 ▾

Payers, providers, PBMs — who pays whom

The flow of money between patients, employers, health plans, providers and pharmacy benefit managers. Why prices are opaque.

Medicare Parts A/B/C/D & Medicaid

Hospital vs outpatient vs Advantage vs drugs. Medicaid as a state program. Who is dual-eligible and why it matters for payment.

Medicare Advantage & capitation (PMPM)

Private plans paid a risk-adjusted monthly amount per member. How the premium flows from CMS to the plan to the provider group.

Fee-for-service vs value-based care

Paying for volume vs paying for outcomes. ACOs, MSSP, ACO REACH, shared savings and shared losses.

Full risk vs non-risk contracts vs risk adjustment

Who bears financial risk is a different axis from how much gets paid. They share a word, not a mechanism.

CMS rulemaking — rate notices & calendars

Advance Notice, Rate Announcement, MA payment timelines. Where model changes (V28, normalization) are announced.

Health plan operations & transitions

Enterprise modernization, M&A integration, vendor and third-party risk inside large health plans.

Clinical code sets & reference data

codes 0/8 ▾

ICD-10-CM & ICD-10-PCS

Diagnosis codes (what the patient has) vs inpatient procedure codes. Code structure, specificity, annual updates.

CPT & HCPCS, modifiers

Procedure and supply codes for professional claims. Level I vs Level II. Modifiers that change payment.

Revenue codes, bill types, place of service

The institutional claim vocabulary. How to tell inpatient, outpatient, SNF and ED visits apart.

MS-DRG — inpatient grouping

How an inpatient stay becomes one payment. MDCs, CC/MCC, relative weights.

NDC & RxNorm

Drug identifiers in pharmacy claims. Mapping NDC to ingredient and therapeutic class.

NPI, TIN & taxonomy — provider identity

Individual vs organizational NPIs, billing vs rendering provider. The NPPES registry as a reference table.

Value sets, CCSR & terminology tables

Grouping thousands of codes into conditions. Why reference tables are load-bearing in every mart.

LOINC & SNOMED CT

Lab results and clinical concepts in EHR data. Where they appear vs where ICD appears.

Healthcare data formats & sources

sources 0/8 ▾

Claims anatomy — professional vs institutional

CMS-1500/837P vs UB-04/837I. Header vs line grain, paid vs allowed vs charged amounts.

X12 EDI — 834, 835, 837

Enrollment, remittance and claim transactions. Loops, segments, and why nobody loves parsing them.

CMS CCLF & ALR files (ACOs)

Claim and Claim Line Feed plus Assignment List Reports. Dual status fields that disagree between files.

MMR & MOR files (Medicare Advantage)

Monthly Membership Report and Model Output Report: what CMS actually paid and which HCCs it recognized.

Synthetic data — Synthea & CMS SynPUF

Realistic fake patients and Medicare claims for building pipelines without PHI. Rule-based simulation (Synthea, Tuva) vs models that learn from a real seed dataset (SDV, synthcity).

Claims data modeling (dbt + Tuva)

modeling 0/8 ▾

The Tuva Project — input layer & core

Open-source dbt package: map raw claims to the input layer, get core tables and marts (HCC, HEDIS, CCSR, readmissions).

Running Tuva locally on DuckDB

dbt + DuckDB for a local lab. Macro errors, file locks, internal assertions — and how to fix them.

Claim adjustments, reversals & final claim logic

Original, void and replacement claims. Building a "latest version" claim without double-counting.

Encounter grouping

Stitching claim lines into encounters. Why clinical ADT/EHR encounters are stacked, not matched or deduped.

Eligibility spans, member months & payer grain

One row per member per month per payer. A grain mismatch can silently drop disease factors.

Attribution — which patient belongs to whom

Plan-assigned vs claims-based attribution. The base table for every VBC report.

Source authority — eligibility vs attributes

Which file is the source of truth for which field. Coalesce and latest-month rules that corrupt dual status.

dbt + Snowflake patterns for PHI

Incremental models on claims, snapshots for enrollment history, masking policies, environment separation.

Risk adjustment

risk 0/8 ▾

CMS-HCC model — V24 → V28

Hierarchical Condition Categories, the model phase-in, which conditions lost weight and why.

ICD-10 → HCC mapping & hierarchies

Many codes map to one HCC. Hierarchies drop the less severe HCC in the same family.

RAF score calculation

Demographic + disease + interaction factors, normalization and coding intensity adjustment. Five pipeline layers end to end.

Dual status & segments

Community vs institutional, full vs partial dual, new enrollee. Why a wrong segment moves the score.

HCC suspecting & recapture

Conditions documented last year but not yet this year. suspecting_gaps and what care teams do with them.

MOR reconciliation vs internal RAF

Comparing your computed score with what CMS paid. Explaining the delta member by member.

RADV audits & documentation (MEAT)

Monitor, Evaluate, Assess, Treat. Why a diagnosis in claims is not enough if the chart does not support it.

HHS-HCC (ACA) & RxHCC

The other risk models: commercial marketplace and Part D. Same idea, different factors.

Quality & value measurement

quality 0/7 ▾

HEDIS measures

Denominators, numerators, exclusions. Measurement year vs lookback. Claims vs supplemental data.

Medicare Star Ratings

How HEDIS, CAHPS, HOS and operations roll up into stars — and into quality bonus payments.

Care gaps, gap closure & AWV

Open gaps per member, Annual Wellness Visit completion, outreach lists for care coordination.

Utilization & cost — PMPM, admits/1000

Per-member-per-month cost, inpatient admits and ED visits per 1000, service category breakdowns.

Claims lag & completion factors (IBNR)

Incurred but not reported. Why last month always looks cheap and how actuaries complete it.

Shared savings & MLR reconciliation

Benchmarks, trend, surplus/deficit sharing. Medical loss ratio in risk contracts.

Data quality & compliance

compliance 0/6 ▾

Claims data quality checks

Fill rates, invalid codes, duplicate claims, orphan members, date sanity. What "quality" means for claims.

Tuva DQI mart & dashboards

Fill rates and anomaly flags for every input field, surfaced in Streamlit.

De-identification — Safe Harbor vs Expert Determination

The 18 identifiers, dates and ZIP codes, when a dataset stops being PHI.

BAAs & third-party risk

Business Associate Agreements with vendors, cloud providers and AI tools. Vendor due diligence.

Testing healthcare dbt projects

Row-count reconciliation against source, unit tests on RAF logic, regression tests across package upgrades.

Analytics & ML on claims

ml 0/6 ▾

Feature engineering from claims

Which features carry signal, which leak, and how to validate them before training.

Patient risk prediction with scikit-learn

Random Forest on the HCC suspecting summary. What the model is and is not.

Population segmentation & cohorts

Rising risk, high utilizers, chronic condition cohorts for care management.

Bias in clinical algorithms

Cost as a proxy for need. The Obermeyer et al. (2019) study and what it means for your models.

LLMs & agents over the healthcare warehouse

Semantic layers and agent context on top of dbt + Snowflake — with PHI constraints.

// bibliography

The books, courses and practice sites behind this roadmap.

// books
Claims Data Analytics ↗
The Tuva Project · free · cited in 24 topics
Claims, eligibility, code sets, groupers, PMPM, quality and HCCs, written by people who build the pipelines. Most topics here cite a chapter.