FHIR R4 Integration

FHIR R4 round-trip

flowchart LR
  APP["SMART app<br/>(external)"] -->|GET / POST /fhir| API["FHIR API<br/>(public-api)"]
  API --> SVC["clinical · administration"]
  SVC --> M[("MongoDB")]
  SVC -. Moleculer events .-> MATCH["fhir-subscription-matcher<br/>(Deno)"]
  MATCH -->|HMAC-signed Bundle| APP

medOS supports FHIR R4 read and write operations with subscription-based event delivery. FHIR is the standard for external healthcare exchange; SMART-on-FHIR apps talk to medOS through the public-api service.

Architecture

SMART App ──▶ FHIR Write API ──▶ Moleculer Services ──▶ MongoDB
  (external)    (public-api)      (clinical, admin)       │
       ▲                                            Moleculer events
       │                                                   │
       │         fhir-subscription-    hospital_events ◀───┘
       │         matcher (Deno)        (Supabase trigger)
       │              │
       └──────────────┘  (FHIR Bundle POST, HMAC signed)

Key components

File locations

Component	Path
Read API	services/public-api/.../modules/fhir/resources/
Write API	services/public-api/.../modules/fhir/resources/fhir-write.controller.ts
Subscriptions (Supabase)	infrastructure/medbase/migrations/021_fhir_subscriptions.sql
Subscription Matcher	infrastructure/medbase/functions/fhir-subscription-matcher/index.ts
Webhook Dispatcher	services/administration/.../webhookDispatcher.service.mixin.ts
CapabilityStatement	services/public-api/.../modules/fhir/fhir-capability.controller.ts
Transformers	services/public-api/.../modules/fhir/transformers/
Admin UI	web/src/common/components/medical/builder/webhooks/FhirSubscription*.tsx
Bundle export	web/src/utils/fhir-bundle-export.ts

Feature flags

Flag	Default	Purpose
fhir.write.enabled	false	Tenant kill switch for FHIR write-back
fhir.subscription.rate_limit	100	Max dispatches/min per subscription

Bundle export (HealthWallet / ExitPath)

web/src/utils/fhir-bundle-export.ts serialises an IPS-compliant FHIR R4 Bundle for patient handoff — used by the HealthWallet QR export and the ExitPath workflow.