Feature ID: CL-16Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
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
| 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.
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 |
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_logis append-only (INSERT only; no UPDATE/DELETE policies).- PHI/EHI access logged; no information blocking; Part 2 consent enforced per CL-11.
updated_byoncl_fhir_resourcesis set at the application layer (edge function), consistent with other CL patterns.
External FHIR Import Addendum
When to use: Choose this path when nativecl_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
- Source: Trusted partner or internal EHR (
source_systemcode registered per org). - 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. - 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).
- Persistence: Store normalized payloads in
cl_fhir_resources(or successor table) withresource_type,resource_id,source_system,received_at,bundle_id,organization_id,chart_idlinkage after patient match (below). - 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_idif 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.