# Future Integration Roadmap v0.3

![Integration Roadmap](../diagrams/integration_roadmap.svg)

---

## Phase Details

### Phase 1 (Current) — Foundation Only

**No live integrations.** Schema designed to be API-ready. Synthetic data for testing.

| Component | Status | Notes |
|---|---|---|
| Database schema | Designed | API-ready tables for all future integrations |
| Healthie form mapping | Designed | YAML config maps Healthie form answers to Core DB columns |
| PHI encryption (DOB) | Implemented | `enc:v1` envelopes; KMS in staging/prod, local key in dev/test (`access_core/services/phi_crypto.py`) |
| Pseudonymization | Designed | HMAC case_id + Safe Harbor mapping — see `docs/security/PHI_Pseudonymization_Design.md`; runtime service deferred |
| AWS infrastructure | Implemented (Terraform) | `infra/` — modules for VPC, KMS, RDS, S3, SQS, Fargate; dev/staging/prod envs. Not yet applied to a live account |
| Synthetic data | Generated | Full-lifecycle cohort generator (`generate_synthetic_cohort`) across CKM/eCKM/MSK tracks with OAP labs + PROM scores |

### Phase 2 — CMS API Integration

**Trigger:** After schema, security, and compliance are finalized.

| API | Purpose | DB Tables | Priority | Effort |
|---|---|---|---|---|
| Eligibility API | Check beneficiary eligibility | `eligibility_checks` | P0 | 2-3 weeks |
| Alignment API | Align beneficiary to participant | `alignments`, `enrollment_decisions` | P0 | 2-3 weeks |
| Data Reporting API | Submit OAP measures | `oap_measure_observations`, `cms_api_requests/responses` | P0 | 3-4 weeks |
| Unalignment API | Remove beneficiary | `unalignment` | P1 | 1-2 weeks |
| Blue Button 2.0 | Historical claims/lab data | `cms_claims_files`, `cms_api_responses` | P2 | 2-3 weeks |

**Sandbox:** `sandbox.bluebutton.cms.gov` | Python SDK: `github.com/CMSgov/cms-bb2-python-sdk`

### Phase 3 — Healthie Production Integration

**Trigger:** After CMS APIs validated in staging. **API validated (GraphQL, sandbox tested).**

- **Patient creation:** GraphQL `signUp` mutation → Core DB stores returned `user.id` as `healthie_id` in `external_system_identifiers`
- **Care plan sync:** `createCarePlan` / `updateCarePlan` mutations — push approved protocol versions to Healthie
- **Daily check-in ingestion:** Healthie webhook pointer → GraphQL query fetch → Core DB daily operations
- **Form ingestion:** `form_answer_group.created` webhook → `formAnswerGroup(id)` query → `daily_checkin_submissions`, `daily_checkin_responses`
- **Document ingestion:** Webhook (document.created/updated) → `documents` GraphQL query → download via `expiring_url` → S3 + `clinical_documents`
- **Metric entries:** `metric_entry.created` webhook → `entry(id)` query → `clinical_observations` / `oap_measure_observations`
- **Safety signals:** `entry.created` (SymptomEntry) + out-of-range metric alerts → `safety_signal_events`
- **Messaging:** Metadata only, not full duplication
- **Recurring forms:** `createRequestedFormCompletion` mutation with `is_recurring: true` for automated daily check-in prompts

**Key:** Healthie webhooks are lightweight pointers only (`resource_id`, `resource_id_type`, `event_type`, `changed_fields`) — worker must make a follow-up GraphQL query to retrieve full resource data.

**Principle:** Healthie is the unified patient-facing and clinical workflow platform. Core DB remains the canonical normalized ACCESS ledger.

### Phase 4 — Cognito Form Field Migration (Planning)

**Trigger:** After CMS APIs validated in staging. **Form field definitions only — no submission data to migrate.**

- **Form fields:** Cognito form definition JS has been extracted and parsed into `Cognito_to_Healthie_Form_Mapping.yaml` (80+ fields across 19 sections). This mapping was used to rebuild the intake form in Healthie.
- **No submission migration:** All patient intake submissions originate from Healthie. Cognito has no submissions that need to be migrated to the Core DB.
- **Deactivation:** Cognito forms are decommissioned once the Healthie intake form is live and validated.

### Phase 5 — Lab Network Integration

**Trigger:** After first beneficiaries are enrolled and generating lab data.

- **Labcorp/Quest API:** Structured lab results → `lab_results` (LOINC mapping)
- **PDF fallback:** Upload → S3 → manual curation workflow
- **Provenance:** Collection date, reporting date, lab facility, method stored

### Phase 6 — Custom Patient Application (Optional)

**Trigger:** When funding, operational SOP, and data model are stable.

- Daily protocol guidance, execution logging, symptom tracking, device integration, care team alerts, patient education
- **Do NOT build before data model, compliance workflow, and first operational evidence are stable.** (Per brief §11.1, §21)

### Phase 7 — FHIR / USCDI / HIE Interoperability

**Trigger:** When payer, investor, or regulatory evidence requirements demand it.

- **FHIR R4:** `clinical_observations` → FHIR Observation; `beneficiaries` → FHIR Patient; `care_periods` → FHIR EpisodeOfCare
- **USCDI v2/v3:** US Core Data for Interoperability subset
- **SMART on FHIR:** Future patient app or third-party integrations

### Phase 8 — Dashboard & Public Reporting

**Trigger:** After sufficient beneficiary enrollment and outcome data.

- Internal dashboard (RBAC, no patient-level export)
- Aggregate outcomes (cell-size suppression n < 10)
- Public reporting (physician + compliance approval; no PHI; CMS vs MetaFlow distinction)

---

## Parallel Tracks (All Phases)

Security/compliance hardening · Synthetic data expansion · Infrastructure automation (Terraform)