FHIR Integration Architecture Diagram
Few hospitals can replace their HL7 v2 interfaces overnight, so most FHIR programmes add an API layer on top of what already exists. This diagram shows that pattern: an interface engine converts HL7 v2 events into FHIR resources, a FHIR R4 server stores and serves them, and an API gateway and authorization server protect access for patient apps and external partners.
Free, no sign-up. The builder runs in your browser; nothing is uploaded.
What this diagram shows
Swap the FHIR server for your EHR’s native FHIR endpoint if it has one — the gateway and authorization layer stay the same.
Components
Patient app
A SMART on FHIR app that signs the user in through OAuth 2.0 / OpenID Connect and calls the FHIR API with an access token limited to that patient.
Partner / payer
A system-to-system client using SMART Backend Services and the FHIR Bulk Data ($export) API for population-level data.
API gateway
Terminates TLS, validates tokens, applies rate limits and logs every call before it reaches the FHIR server.
Authorization server
Issues OAuth 2.0 access tokens with SMART scopes that limit which resources a client can read or write.
FHIR server
Stores and serves FHIR R4 resources such as Patient, Encounter, Observation, DiagnosticReport and ImagingStudy through a RESTful API.
Interface engine
Listens to HL7 v2 feeds and converts them into FHIR resources, posting them to the server as transaction Bundles.
EHR / EMR
The source system, still emitting HL7 v2 ADT and ORU messages.
How the data flows
Source events
The EHR emits ADT and ORU messages as it always has.
Convert
The interface engine maps PID to Patient, PV1 to Encounter, OBR to DiagnosticReport and OBX to Observation, and posts them to the FHIR server as one transaction Bundle so related resources are written together.
Authorize
Apps and partners get an access token from the authorization server. Patient apps use the SMART App Launch flow; backend clients authenticate with a signed JWT.
Call the API
Requests pass through the API gateway, which validates the token and forwards permitted calls to the FHIR server.
Bulk export
Partners call $export and receive NDJSON files for whole populations asynchronously, instead of paging through millions of searches.
Interfaces in this diagram
Every connection in the diagram, ready to copy into an interface register or test plan.
| # | From | To | Protocol | Detail |
|---|---|---|---|---|
| 1 | Patient App (SMART on FHIR) | →API Gateway (TLS · Throttling) | FHIR | REST · OAuth |
| 2 | Partner / Payer (Bulk Data client) | →API Gateway (TLS · Throttling) | FHIR | Bulk $export |
| 3 | API Gateway (TLS · Throttling) | ↔Auth Server (OAuth 2.0 / OIDC) | API | OAuth 2.0 |
| 4 | API Gateway (TLS · Throttling) | ↔FHIR Server (R4 Resources) | FHIR | — |
| 5 | Interface Engine (HL7 v2 → FHIR) | →FHIR Server (R4 Resources) | FHIR | Transaction |
| 6 | EHR / EMR (HL7 v2 source) | →Interface Engine (HL7 v2 → FHIR) | HL7 | ADT · ORU |
Design considerations
- Pick the FHIR version and implementation guides (for example US Core or your national profiles) before mapping, not after.
- Make the HL7 v2 → FHIR conversion idempotent: replays and A08 updates must update resources, not duplicate them. Use stable identifiers.
- Keep authorization in front of the FHIR server so new clients can be added without redeploying it.
- Log every access with user, client and patient context for audit (IHE ATNA / BALP).
- Decide what happens to HL7 v2 data with no clean FHIR home — Z-segments and free-text OBX values need explicit rules.
Related reference
Frequently asked questions
What is a FHIR server?
A FHIR server stores healthcare data as FHIR resources (Patient, Observation, Encounter and so on) and exposes them over a RESTful API with standard search, create, update and history operations. Examples include HAPI FHIR, Azure Health Data Services, Google Cloud Healthcare API and AWS HealthLake.
How does HL7 v2 map to FHIR?
Segments map to resources: PID → Patient, PV1 → Encounter, ORC/OBR → ServiceRequest and DiagnosticReport, OBX → Observation, AL1 → AllergyIntolerance. HL7 publishes an official v2-to-FHIR mapping guide, and the free Majware converter shows the result for any message.
What is SMART on FHIR?
SMART on FHIR adds OAuth 2.0 and OpenID Connect authorization to FHIR APIs, so third-party apps can launch from an EHR or a patient portal and access only the data the user has permitted.
Do I still need an interface engine with FHIR?
Usually yes. Most clinical systems still speak HL7 v2, so the engine remains the place where events are captured, converted and routed. FHIR typically adds an API for apps and partners rather than replacing internal messaging.
Make it match your site
Rename systems, add your AE titles and message types, then export PNG, SVG or PDF — or send a colleague a share link.