Skip to main content
Feature ID: CL-16
Status: 📝 Planned
Spec: 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

​
Integration Points (from Spec)

​
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 (to be authored for Phase 1 endpoints before implementation).

​
Event Contracts

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 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.