> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 0 · The Six Layers

> Why a healthcare starter exists at all: raw codes are unusable. There are ~70,000 ICD-10 codes — "how many members have diabetes?" isn’t one code, it’s a whole branch. The start… (~15 min)

Why a healthcare starter exists at all: **raw codes are unusable.** There are \~70,000 ICD-10 codes — "how many members have diabetes?" isn't one code, it's a whole branch. The starter pre-maps those into meaningful groups using public AHRQ/CMS standards, pins one governed definition for contested metrics like PMPM and readmission, wires risk adjustment (HCC/RAF) to the official CMS model, and makes HIPAA-aligned behavior the default.

## The six layers

<table>
  <tr><th>Layer</th><th>Where</th><th>What</th></tr>
  <tr><td>**1 — Entity spine**</td><td>`ontology/schema.tql`, `ontology/relations/`</td><td>Member, Provider, Coverage, Medical/Pharmacy Claim, Encounter, Diagnosis, Procedure, Drug.</td></tr>
  <tr><td>**2 — Metrics**</td><td>`ontology/queries/`</td><td>Governed surfaces: PMPM, readmission, prevalence, comorbidity/RAF, utilization/1000, Rx adherence, HEDIS template.</td></tr>
  <tr><td>**3 — Terminology**</td><td>`ontology/dimensions/`, `filters/`, `reference/terminology/`</td><td>**The heart.** ICD-10 hierarchy + groupers (CCSR, CMS-HCC, CCW) as dimensions, filters & committed crosswalks.</td></tr>
  <tr><td>**4 — Governance & PHI**</td><td>`ontology/notes/governance-phi.md`, `config/org_context.md`</td><td>HIPAA minimum-necessary, \<11 suppression, 42 CFR Part 2.</td></tr>
  <tr><td>**5 — Decision records**</td><td>`ontology/notes/`</td><td>Why each metric is defined the way it is; canonical grouper per question; the glossary, claim-grain, and join-verification guides.</td></tr>
  <tr><td>**6 — Validation**</td><td>`validation/`</td><td>`validate_tql.py` (every surface checked against your live schema + compiled), golden queries with pinned values, the dry-run + A/B playbooks.</td></tr>
</table>

<Note>
  **Standards alignment** —

  `STANDARDS.md` maps the model to the industry data models it aligns with (Tuva, OMOP, FHIR, X12). The semantic layer (metrics, routing, terminology) is **fully separated from the physical mapping**: every physical table name lives in **one file**, `ontology/schema.tql` — re-point it and the metric logic stays put. The starter is authored Redshift-first with BigQuery equivalents inline; `MIGRATION.md` is the 8-step re-point checklist and works the same for commercial, Medicare, or Medicaid warehouses on Redshift, BigQuery, Snowflake, or **Databricks** (budget: about a half-day with warehouse access). For a deep technical tour, read `DEEP_DIVE.md`.
</Note>

### ✅ Checkpoint

* [ ] You can name the six layers and find each one in the repo
* [ ] You know which code systems ship in the box vs. need your own license/key
* [ ] You know the default dialect (Redshift-first, Tuva-shaped) and where BigQuery notes live

<Note>
  **Two rules for a long, live session** —

  **1 · Checkpoint every couple of modules.** Long threads have a ceiling. After every module or two, ask Ana: *“Save a handoff document summarizing what we've built, what we decided, and what's next — so we can continue in a new thread.”* If a thread ever maxes out, you lose nothing.<br /><br />
  **2 · Pin the scope in every prompt.** Name the **entity** and the **source-of-truth tables** in each prompt (“…for \[entity X], using the \[base] tables, not the summary table”) — otherwise Ana may drift to a convenient summary table or query every source at once.
</Note>