> **MIGRATION SOURCE ONLY.** Cognito is the legacy intake platform. Healthie Forms replace Cognito as the unified patient-facing and clinical workflow platform. See `Cognito_to_Healthie_Form_Mapping.yaml` for the Healthie migration spec. This file documents how existing Cognito data maps to Core DB columns during migration.

**How this works as a configurable system:**

1. **The YAML is the single source of truth** for Cognito → DB mapping. When Cognito's form changes (new fields, renamed fields, new sections), you update this file — not the ingestion code or the schema.

2. **The ingestion pipeline reads this file** at startup, parses the mapping, and applies the transforms defined (`json_array_to_list`, `timestamp_ms_to_date`, `yes_no_to_boolean`, etc.). Unmapped fields are still captured in `raw_payload` on `raw_ingestion_records` so nothing is lost.

3. **Two-stage identity (v2.0 change):** Cognito identity fields map to `intake_records` first. The `beneficiaries` table is populated only after the full enrollment workflow completes (eligibility check + consent + alignment + physician approval). This is the key difference from v1.0.

4. **Conditional sections** (female/male health) are gated by the `condition` key, referencing `intake_record.sex` (was `beneficiary.sex` in v1.0).

5. **`transform: "collect_into_jsonb"`** groups related fields into a single JSONB column instead of creating individual columns — useful for sections like mouth/throat/ear/eye where the fields are numerous and closely related.

6. **Derived columns** (like `exclusion_flags`) reference application logic rather than a direct field — the pipeline calls a rules engine after normalization.

7. **`form_version`** is tracked at the mapping level, so if the form changes, historical records retain their original version context for auditability (per §9.1).

**Note:** This mapping is based on Cognito's form definition JS (complete field data) and an XLSX export sample (value format reference). The form definition JS provides accurate field labels, types, choices, and structure. Value format transforms should be validated during migration.

## Transforms

| Transform | Purpose |
|---|---|
| `json_array_to_list` | Parse `"Opt 1", "Opt 2"` → `["Opt 1", "Opt 2"]` |
| `timestamp_ms_to_date` | `1593561600000` → `2020-06-30` |
| `timestamp_ms_to_datetime` | `1783704300000` → `2026-07-09 15:45:00` |
| `yes_no_to_boolean` | `"Yes"` → `true`, `"No"` → `false` |
| `stringify` | `1` → `"1"` (for middle name edge case) |
| `collect_into_jsonb` | Multiple fields → single `{"field1": val, "field2": val}` |

## v1.0 → v2.0 Changes

| Area | v1.0 | v2.0 |
|---|---|---|
| Identity table | `beneficiaries` + `beneficiary_identifiers` | `intake_records` + `intake_identifiers` |
| Condition key | `beneficiary.sex` | `intake_record.sex` |
| Beneficiaries creation | At intake | Only after eligibility + consent + alignment |
| Version | `mapping_version: "1.0"` | `mapping_version: "2.0"` |
| Webhook fields | Not included | `webhook_signature_valid`, `processing_status` in `raw_ingestion_records` |

## Healthie Integration Notes

Healthie uses a **GraphQL API** (not REST). The integration pattern differs from Cognito:

| Aspect | Cognito | Healthie |
|---|---|---|
| API type | REST (webhook POST) | GraphQL (mutations + queries) |
| Webhook payload | Full form submission | Lightweight pointer (resource_id, event_type, changed_fields) |
| Ingestion steps | 1: webhook → store → normalize | 2: webhook → fetch full resource → store → normalize |
| Authentication | Webhook signature verification | API key (sandbox validated) |
| Identity linkage | `intake_records` → `beneficiaries` | `external_system_identifiers.system = "healthie"` |

**Patient creation is outbound** — Core DB pushes to Healthie via `signUp` mutation after enrollment is approved + CMS aligned. Healthie returns `user.id` which is stored as the `healthie_id` in `external_system_identifiers`.

**Daily operations are inbound** — Healthie webhooks notify of patient events; worker fetches full data via GraphQL query, then stores in `clinical_documents`, `daily_checkin_submissions`, etc.