Interoperability - FHIR & HIN

US-market ready. USCDI v3 compliant. SMART on FHIR. C-CDA import/export. Connected to Carequality + CommonWell via Metriport.

---

Overview

MedOS implements a complete interoperability stack for US healthcare compliance:

Capability	Standard	Status
FHIR R4 API	HL7 FHIR R4	Implemented (9 resource mappers)
C-CDA Import/Export	HL7 CDA R2	Implemented (9 section mappers)
SMART on FHIR	OAuth2 + PKCE	Implemented
EHI Export	21st Century Cures Act	Implemented (CCDA, FHIR Bundle, NDJSON)
HIN Connectivity	Carequality, CommonWell	Implemented via Metriport
HIPAA Audit	45 CFR 164.312(b)	Implemented (immutable audit log)
HL7v2	HL7 v2.x	Schema defined, parser planned

---

Architecture Diagram

┌──────────────────────────────────────────────────────────────────────────────┐
│                    HEALTH INFORMATION NETWORKS (HIN)                          │
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │  Carequality  │  │  CommonWell  │  │  eHealth     │  │  Direct      │    │
│  │  250M+ pts    │  │  70M+ pts    │  │  Exchange    │  │  Trust       │    │
│  │  IHE XCA/XCPD│  │  REST/FHIR   │  │  IHE-based   │  │  Messaging   │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         └──────────────────┴──────────────────┴──────────────────┘           │
│                                    │                                         │
│                                    ▼                                         │
│                    ┌──────────────────────────────┐                          │
│                    │  METRIPORT (Abstraction Layer) │                          │
│                    │  Unified API for all networks  │                          │
│                    └──────────────┬───────────────┘                          │
└──────────────────────────────────┬───────────────────────────────────────────┘
                                   │
                    ┌──────────────┴────────────────┐
                    │                               │
                    ▼                               ▼
┌───────────────────────────┐    ┌──────────────────────────────────────────┐
│  fhir-webhook             │    │  ever-api-interoperability               │
│  (Supabase Edge Function) │    │  (Moleculer Microservice)                │
│                           │    │                                          │
│  Receives:                │    │  Modules:                                │
│  • document-download      │    │  ┌─────────┐ ┌──────┐ ┌─────────────┐  │
│  • document-conversion    │    │  │  CCDA    │ │ HIN  │ │ EHI Export  │  │
│  • consolidated-data      │    │  │ Import/  │ │Query/│ │ FHIR Bundle │  │
│  HMAC-SHA256 verified     │    │  │ Export   │ │Send  │ │ CCDA/NDJSON │  │
│                           │    │  └─────────┘ └──────┘ └─────────────┘  │
│  Writes to:               │    │                                          │
│  • fhir_hin_documents     │    │  ┌─────────────────────────────────────┐ │
│  • fhir_hin_patient_map   │    │  │  9 FHIR R4 Mappers (USCDI v3)     │ │
│  • fhir_audit_log         │    │  │  Patient, Encounter, Condition,     │ │
│                           │    │  │  MedicationRequest, Observation,    │ │
│                           │    │  │  AllergyIntolerance, Procedure,     │ │
│                           │    │  │  Immunization, DocumentReference    │ │
│                           │    │  └─────────────────────────────────────┘ │
└───────────────────────────┘    └──────────────────────────────────────────┘
                                               │
                    ┌──────────────────────────┤
                    │                          │
                    ▼                          ▼
┌───────────────────────────┐    ┌──────────────────────────────────────────┐
│  SMART on FHIR            │    │  CCDA Generator                          │
│  (service-kit)            │    │  (ever-ccda-generator)                   │
│                           │    │                                          │
│  OAuth2 + PKCE            │    │  Blue Button+ format                     │
│  EHR Launch / Standalone  │    │  9 section mappers:                      │
│  Scopes:                  │    │  demographics, allergies, medications,   │
│  • patient/*.read         │    │  problems, procedures, encounters,       │
│  • launch, openid, fhirUser│   │  immunizations, results, vitals          │
│  • offline_access         │    │                                          │
│  Token refresh + smartFetch│   │  Input: medOS entities → Output: XML     │
└───────────────────────────┘    └──────────────────────────────────────────┘
                                               │
                                               ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                         AUDIT & COMPLIANCE                                    │
│                                                                              │
│  ┌─────────────────────────────┐  ┌──────────────────────────────────────┐  │
│  │  InteropAuditLog (MongoDB)  │  │  fhir_audit_log (Supabase)           │  │
│  │  Direction, format, outcome │  │  HIPAA 45 CFR 164.312(b)            │  │
│  │  Action, endpoint, latency  │  │  Immutable (no UPDATE/DELETE)        │  │
│  │  Formats: CCDA, FHIR, HL7  │  │  Actions: CREATE, READ, EXPORT,     │  │
│  │                             │  │    QUERY, SHARE, LOGIN, LOGOUT       │  │
│  └─────────────────────────────┘  │  RLS: admin/compliance officer only  │  │
│                                    └──────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘

---

FHIR R4 Resource Coverage (USCDI v3)

FHIR Resource	MedOS Source	LOINC/SNOMED Codes
Patient	Patient demographics	MRN: medos.health/fhir/sid/mrn, National ID, SSN
Encounter	Encounter records	Visit type, class, period
Condition	Problems/Diagnoses	ICD-10 codes
MedicationRequest	Prescriptions	RxNorm, ATC codes
Observation (Vitals)	Vital signs	BP: 8480-6/8462-4, HR: 8867-4, Temp: 8310-5, SpO2: 59408-5
Observation (Labs)	Lab results	LOINC codes per test
AllergyIntolerance	Allergies	SNOMED CT
Procedure	Procedures	CPT, SNOMED CT
Immunization	Immunizations	CVX codes
DocumentReference	Documents	LOINC document types

---

SMART on FHIR (Patient Portal & EHR Integration)

Third-Party App                    MedOS FHIR Server
      │                                  │
      │  1. GET /.well-known/smart-config │
      │ ────────────────────────────────▶ │
      │                                   │
      │  2. Redirect to auth endpoint     │
      │     + PKCE code_challenge          │
      │ ────────────────────────────────▶ │
      │                                   │
      │  3. User authorizes scopes         │
      │ ◀──────────────────────────────── │
      │                                   │
      │  4. Exchange code + code_verifier  │
      │ ────────────────────────────────▶ │
      │                                   │
      │  5. Access token + refresh token   │
      │ ◀──────────────────────────────── │
      │                                   │
      │  6. smartFetch('/Patient/123')     │
      │     Bearer: <access_token>         │
      │ ────────────────────────────────▶ │

Scope bundles:

• PATIENT_SUMMARY_READ — for HIN connectors (read-only clinical data)
• FULL_CLINICAL — for trusted EHR integrations (read + write + offline_access)

---

EHI Export (21st Century Cures Act)

Patients can request a complete export of their health information:

Format	Output	Use Case
CCDA	C-CDA XML	Traditional document exchange
FHIR Bundle	FHIR R4 JSON	Modern app consumption
NDJSON	Newline-delimited JSON	Bulk data export

Flow: Request → Aggregate from all services → Build export → Store in filestore → 30-day download link

Export summary tracks: Patient, Encounter, AllergyIntolerance, MedicationRequest, Observation, Condition counts.

---

ONC Compliance Checklist

Requirement	CFR Reference	MedOS Implementation
Transitions of Care	45 CFR 170.315(b)(1)	C-CDA import/export with 9 section mappers
SMART App Launch	45 CFR 170.315(g)(10)	OAuth2 + PKCE, EHR Launch + Standalone
EHI Export	21st Century Cures	3 formats (CCDA, FHIR Bundle, NDJSON), 30-day link
Audit Logging	45 CFR 164.312(b)	Immutable fhir_audit_log, RLS, no UPDATE/DELETE
USCDI v3 Data	ONC USCDI	9 FHIR resource types mapped with standard terminologies
API Access	45 CFR 170.315(g)(7-10)	FHIR R4 REST API via ever-public-api