FHIR R4 Integration

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.

R4

FHIR version

HMAC

Signed dispatch

Deno

Matcher runtime

100/min

Default rate limit

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

Read

FHIR Read API

GET / search for Patient, Encounter, Observation, Condition.

PatientEncounterObservationCondition

Write

FHIR Write API

POST / PUT / PATCH with reverse mappers → medOS domain models.

POSTPUTPATCH

Subscribe

FHIR Subscriptions

`fhir_subscriptions` + delivery log tables in Supabase.

fhir_subscriptionsdelivery_log

Dispatch

Subscription Matcher

Deno edge function: criteria matching + FHIR dispatch.

Denoedge function

Webhook

Webhook Dispatcher

`payloadFormat: 'fhir'` wraps events in FHIR Bundles, HMAC-signed.

HMACBundle

Meta

CapabilityStatement

GET /fhir/metadata advertising supported resources.

CapabilityStatement

Mappers

Transformers

Bidirectional medOS ↔ FHIR transformers per resource type.

medOS → FHIRFHIR → medOS

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.