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

# FHIR Interoperability & Data Exchange — Integration

> Feature ID: CL-16 Status: \U0001F4DD Planned -fhir-interoperability-data-exchange.md Last Updated: 2026-03-25

**Feature ID:** CL-16\
**Status:** 📝 Planned\
**Spec:** [CL-16-fhir-interoperability-data-exchange.md](../../../specs/cl/specs/CL-16-fhir-interoperability-data-exchange.md)\
**Last Updated:** 2026-03-25

***

## Overview

CL-16 exposes FHIR R4 APIs and C-CDA 2.1 exchange for interoperability with payers, HIEs, and patient access. It depends on CL-01 (patient chart), CL-11 (consent/Part 2), CL-12 (care transitions), and PM-10 (prior authorization). Integration uses API contracts and Platform Integration Layer; Arizona Contexture HIE connectivity is via secure messaging and C-CDA.

**Architecture Decision (Errata E-1):** Supabase Edge Functions as FHIR facade for initial implementation, with migration path to Hybrid (Edge Functions + external FHIR server) for ONC certification. Edge Functions expose FHIR endpoints and translate to/from the internal data model.

***

## Implementation Phases

| Phase   | Scope                                                   | Prerequisites                                  | Status                |
| ------- | ------------------------------------------------------- | ---------------------------------------------- | --------------------- |
| Phase 1 | Schema + RLS + basic FHIR Edge Function facade          | cl\_has\_org\_access, CL-01, CL-11 (all exist) | 📝 Ready              |
| Phase 2 | USCDI v3 mapping + C-CDA generation + Contexture HIE    | Phase 1, DirectTrust enrollment (external)     | 📝 Blocked (external) |
| Phase 3 | Da Vinci CRD/DTR/PAS + bulk export + FHIR Subscriptions | Phase 2, PM-10 Da Vinci (not implemented)      | 📝 Blocked (PM-10)    |

***

## Integration Points (from Spec)

| Dependency                  | Pattern        | Purpose                                                                                                                              |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| CL-01 (Patient Chart)       | API / Data     | Chart data sourced for FHIR resources and C-CDA generation                                                                           |
| CL-11 (Consent / Part 2)    | API / RLS      | Consent-gated access; SUD/Part 2 enforcement on all EHI export and API access                                                        |
| CL-12 (Care Coordination)   | API / Event    | Transition summaries (C-CDA 2.1) and FUH tracking; ADT and transition events. Note: C-CDA generation is deferred to CL-16 Phase 2    |
| PM-10 (Prior Authorization) | API            | Da Vinci CRD/DTR/PAS for prior auth; FHIR coverage and PAS submission. **Phase 3 prerequisite — Da Vinci layer not yet implemented** |
| Arizona Contexture HIE      | API / External | C-CDA 2.1, DirectTrust secure email; HIE connectivity and audit in cl\_data\_exchange\_log                                           |

***

## API Contracts

* **FHIR R4 API:** US Core resource types (Patient, Condition, MedicationRequest, CarePlan, DocumentReference, Observation, Encounter, AllergyIntolerance). All reads/writes scoped by organization\_id and consent (CL-11). Logged to cl\_data\_exchange\_log.
* **Patient access API (\$patient-everything):** Bulk export; consent and RLS enforced; access logged.
* **Da Vinci CRD/DTR/PAS:** Prior authorization request/response; PM-10 integration; credentials and endpoints via env/secrets. **Phase 3 — requires PM-10 Da Vinci implementation.**

**Full API contract entries:** See [API\_CONTRACTS.md](./API_CONTRACTS.md) (to be authored for Phase 1 endpoints before implementation).

***

## Event Contracts

| Event Name                  | Publisher | Consumers                        | Trigger                                            | Phase   |
| --------------------------- | --------- | -------------------------------- | -------------------------------------------------- | ------- |
| `cl_fhir_bundle_exported`   | CL-16     | PF-04 Audit, PF-10 Notifications | \$patient-everything or bulk FHIR export completed | Phase 1 |
| `cl_ccda_document_sent`     | CL-16     | PF-04 Audit, GR Compliance       | C-CDA document sent to HIE                         | Phase 2 |
| `cl_ccda_document_received` | CL-16     | CL-01 Chart, PF-10 Notifications | C-CDA document received from HIE                   | Phase 2 |

**Payload requirements:** All payloads must include `organization_id`, `chart_id` (when applicable), and `exchange_type`. No PHI/PII in event payloads — use IDs only.

**Registered in:** `src/platform/events/types.ts` (KnownEventName). Full contracts to be documented in [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md) during implementation.

***

## Behavioral Health Profile Roadmap (Enhancement EN-3)

CL-16 data contracts should plan for US Behavioral Health Profiles IG (v0.1.0) and USCDI+ BH extensions:

* **BH-specific FHIR profiles:** MentalHealthCondition, SubstanceUseCondition, BehavioralHealthCarePlan
* **BH observations:** PHQ-9, GAD-7, C-SSRS, AUDIT-C as FHIR Observation resources
* **Timeline:** After US BH Profiles IG reaches STU1 ballot; tracked in Phase 2+ roadmap

***

## Authentication and Secret Handling

* FHIR and HIE endpoints: credentials (client\_id, client\_secret, HIE certs) in environment/secrets only; never in code or migrations.
* All API access authenticated; tenant context (organization\_id) and consent (CL-11) enforced before data release.

***

## Platform Integration Layer Usage

* CL-16 is owned by CL core; no direct imports from PM or other cores. Integration with PM-10 (prior auth) and scheduling/registration (PM) via documented API or edge function contracts. Chart and consent data accessed via CL-01 and CL-11 within CL or via platform layer where applicable.

***

## Security and RLS

* RLS on cl\_fhir\_resources and cl\_data\_exchange\_log; organization\_id and consent checks via SECURITY DEFINER where needed; WITH CHECK on UPDATE per constitution §5.2.4.
* `cl_data_exchange_log` is append-only (INSERT only; no UPDATE/DELETE policies).
* PHI/EHI access logged; no information blocking; Part 2 consent enforced per CL-11.
* `updated_by` on `cl_fhir_resources` is set at the application layer (edge function), consistent with other CL patterns.

***

## External FHIR Import Addendum

**When to use:** Choose this path when **native** `cl_immunizations` / `cl_procedures` (Phase **1b**) is **deferred** but the org still needs USCDI v3–class **Immunization** and **Procedure** data in-chart for reporting, care management, or interim certification positioning. This is **Option C** in the CL-16 **Certification Path Decision** — it **does not** replace ONC-native storage requirements for full certification claims; it documents an auditable interim pipeline.

### Data flow

1. **Source:** Trusted partner or internal EHR (`source_system` code registered per org).
2. **Ingress:** HTTPS POST to a dedicated **Edge Function** (e.g. `fhir-import-bundle`) with org-scoped JWT / service role pattern consistent with other CL edge functions.
3. **Validation:** Server-side FHIR R4 structural validation + profile checks where configured; reject invalid bundles with structured error (no partial silent drops for required USCDI elements).
4. **Persistence:** Store normalized payloads in **`cl_fhir_resources`** (or successor table) with `resource_type`, `resource_id`, `source_system`, `received_at`, `bundle_id`, `organization_id`, `chart_id` linkage after **patient match** (below).
5. **Downstream:** Read path mappers prefer native tables when present; otherwise surface imported resources through the same FHIR read facade with provenance flags.

### Patient matching & reconciliation

* **Matching keys (in order):** internal `chart_id` if supplied and RLS-valid; else verified MRN + org; else verified identifier system/value pair agreed in integration contract.
* **Ambiguity:** Queue for **reconciliation UI** (CL ops); never attach a bundle to two charts without human confirmation.
* **Audit:** Every match decision logged to `cl_data_exchange_log` (or equivalent) with actor, timestamp, and match rule used.

### Security & compliance

* **Tenant isolation:** All writes scoped by `organization_id`; RLS same as CL-16 Phase 1 facade.
* **Consent / Part 2:** Import MUST respect CL-11 gates — SUD-related resources require explicit consent flags before persistence or merge.
* **PHI minimization:** Edge logs contain correlation IDs only; no resource bodies in application logs.

### ONC / certification impact

* **Gap:** Relying on import-only storage for Immunization/Procedure **without** native tables blocks claiming full **USCDI v3** / ONC criteria that require **CURES API** and structured clinical data in the certified product’s datastore.
* **Documentation:** Product and compliance docs MUST label this period as **interim import** until Phase **1b** native tables ship.

### Operational requirements

* **Idempotent ingest:** `(organization_id, bundle_id)` or `(organization_id, source_system, source_message_id)` MUST dedupe retries.
* **Monitoring:** Alert on validation failure rate, unmatched patient rate, and backlog depth for reconciliation queue.

***

## Related Docs

* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [API\_CONTRACTS.md](./API_CONTRACTS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)