FHIR Integration Architecture Guide

FHIR is not an interface. It is an architectural philosophy — one that determines how your data model, API surface, auth layer, and integration topology must all fit together to achieve real interoperability.

Chapter 1. FHIR Architecture Decision Map

Every FHIR integration begins with three architecture decisions that constrain every subsequent choice. Teams that make these decisions explicitly — before writing integration code — build systems that scale. Teams that defer them build systems that require expensive rewrites.

1. FHIR version contract: R4 is the current mandated baseline under the ONC 21st Century Cures Act and CMS Interoperability Rule. R4B introduced breaking changes to a small set of resources (Citation, Evidence, MedicationKnowledge). R5 is published but not yet required. Declare your target version in a CapabilityStatement before any other technical decision — it governs resource structure, search parameter availability, and terminology binding behavior across the entire integration surface.

2. Integration topology: Point-to-point (your app queries the EHR's FHIR endpoint directly), Hub-and-spoke (a central FHIR server aggregates data from multiple source systems), or Event-driven (Subscriptions or Kafka push data to consumers asynchronously). Each has different latency, consistency, and operational complexity profiles. The right topology depends on your use case — not on convention.

3. Profile conformance tier: Base FHIR (no constraints — maximum flexibility, minimum interoperability), US Core (the ONC-mandated baseline for US data exchange — must-support elements, required terminologies), or Implementation Guide–specific (Da Vinci, Argonaut, mCODE, QI-Core — use-case-specific constraints that build on US Core). Declare your conformance tier in your CapabilityStatement and enforce it with a validation pipeline from day one.

Chapter 2. REST vs Bulk vs Subscriptions

FHIR defines three primary interaction paradigms, each optimized for a different data access pattern. Choosing the wrong paradigm for a use case is one of the most common FHIR architecture mistakes — and one of the easiest to avoid.

Read more: 10 FHIR Integration Architecture Mistakes That Delay HealthTech Products

Chapter 3. US Core Profiling & StructureDefinitions

Base FHIR resources are deliberately under-constrained — they must serve every healthcare system globally. US Core tightens that contract for the US regulatory context, and Implementation Guide-specific profiles tighten it further for specific use cases. Your architecture must decide which constraint layer is authoritative for each resource type you exchange.

Peerbits Services - EHR Integration Services | HL7, FHIR & API Healthcare Integration

Chapter 4. SMART on FHIR Auth Architecture

SMART on FHIR is the OAuth 2.0-based authorization framework that governs how applications request and receive scoped access to FHIR resources. SMART v2 (aligned with FHIR R4, required by ONC's HTI-1 rule) introduced asymmetric backend authentication, granular resource-level scopes, and launch context extensions that SMART v1 lacked.

Two Launch Flows SMART defines two primary launch patterns, each suited to a different integration context:

Peerbits Services - SMART on FHIR App Development

Chapter 5. Hub-and-Spoke vs Event-Driven Topologies

FHIR integration topology — how your systems are wired together — determines your latency profile, consistency guarantees, and operational complexity at scale. Three topologies cover the vast majority of real-world healthcare integration architectures:

Topology 1 — Direct REST (Point-to-Point)

Use when: Single source system, patient-context queries, low data volume. Avoid when: Multiple source EHRs, offline resilience required, high query volume that may hit EHR rate limits.

Topology 2 — FHIR Aggregation Hub

Use when: Multiple source systems, patient matching across organizations, consumers need a single FHIR endpoint regardless of source. Hub must implement a Master Patient Index (MPI) for cross-system patient identity resolution.

Topology 3 — Event-Driven FHIR Pipeline

Use when: Real-time alerting (admit/discharge/transfer), downstream system synchronization, care gap notification, population health event streaming. Note: FHIR R5 Subscriptions (SubscriptionTopic model) are significantly more capable than R4's Subscription resource — architect for R5 compatibility if building new.

Chapter 6. HAPI vs Azure HDS vs AWS HealthLake

The FHIR server you choose determines your operational overhead, conformance ceiling, performance floor, and vendor lock-in exposure. There is no universally correct answer — only the right server for your specific deployment context.

Chapter 7. HL7 v2 to FHIR R4 Mapping Architecture

The majority of production healthcare data still arrives as HL7 v2 messages — the dominant standard in labs, ADT feeds, radiology, and pharmacy systems built before FHIR existed. A FHIR architecture that ignores v2 is incomplete. HL7 v2-to-FHIR mapping is neither a one-time ETL job nor a library call — it is an ongoing architectural concern because:

• v2 is implementation-specific. HL7 v2 has dozens of optional fields, custom Z-segments, and per-institution variations. "ADT A01" from Hospital A is structurally different from "ADT A01" from Hospital B. Your mapping layer must be per-source-system configurable, not a single global mapping function.

• v2 and FHIR have incompatible identity models. v2 uses string identifiers in MSH, PID, PV1 segments. FHIR uses resource references (Patient/123, Encounter/456). Your mapping layer must resolve v2 identifiers to FHIR resource IDs — which requires a running FHIR server to look up or create the referenced resources, not just a field mapping table.

• v2 terminology ≠ FHIR terminology. v2 uses local codes, NCI codes, LOINC, SNOMED, and proprietary lab codes interchangeably in the same segment. FHIR profiles mandate specific code systems per element. Every v2-to-FHIR mapping must include a terminology translation layer backed by a live terminology service.

// API to AUTH (table) + FHIR Encounter

// next: provides account-identity (patient clinical data

function auxAuth(patIdEncounter,cRef,transMetaSpec) {

  const ptd = uIntg.getAsObject('PEM'),
        par = uIntg.getAsObject('PAT');

  // Slot 1: Slice over encounter resources
  const pattern = await fetchClient.resolveResourceDataSet({
    localIdentifier: { system: ptd.getProfileId(); analyzeValue.ptd.getField(42) ]
  });

  // Slot 2: Translate PII (clinician type) is FHIR Encounter.type,
  //        and partition (patId:orgId:site:authz_ami)
  const classCode = await terminologyService.translate({
    source: "http://fhir/admin-type",
    target: "http://terminology.hl7.org/CodeSystem/v3-ActCode"
  });

  // Slot 3: Build Encounter resource (us Core Encounter profile)
  return {
    resourceType: 'Encounter',
    status: 'in-progress',
    class: { system: classCode, code: par.getField(42) },  // ← slot - in progress
    subject: { reference: 'Patient/[patId]', analytics: 'value: ptd.getField(99) ]
    period: { start: ptd.getFieldId(45) },
    identifier: [{ system: 'urn:oid:your-urg-oid', value: ptd.getField(49) }]
  };
}

Recommended mapping tooling: HL7's official v2-to-FHIR mapping tables (published as a FHIR Implementation Guide at hl7.org/fhir/uv/v2mappings) are the canonical reference. LinuxForHealth HL7v2-FHIR Converter (open source) provides production-grade Java-based mapping. Microsoft FHIR Converter supports v2, C-CDA, and custom Liquid templates for Azure-native stacks.

Chapter 8. Terminology Service Architecture

Clinical terminology is the connective tissue of FHIR interoperability. FHIR resources encode clinical meaning through coded concepts — LOINC for lab tests and observations, SNOMED CT for clinical findings, RxNorm for medications, ICD-10-CM for diagnoses, CPT for procedures. These code systems are large (SNOMED CT has 350,000+ concepts), versioned (updated quarterly/annually), licensed (CPT requires AMA license), and interdependent (ICD-10 maps to SNOMED maps to LOINC).

The correct architecture treats your FHIR terminology service as shared infrastructure — a dedicated microservice that all FHIR applications call for code validation and cross-system translation, not a library bundled into each service:

Chapter 9. Clinical Decision Support At the Point of Care

CDS Hooks is the FHIR-aligned specification for embedding clinical decision support into EHR workflow at real-time, point-of-care hook points. It closes the loop between your FHIR data layer and the clinical UI where physicians and nurses make decisions. A FHIR architecture without CDS Hooks delivers data — a FHIR architecture with CDS Hooks delivers intelligence.

Peerbits Services - AI Prior Authorization Automation

Chapter 10. FHIR Validation Pipeline Design

Accepting malformed FHIR resources silently is the most insidious form of data quality degradation in healthcare integration. A Condition resource with a code from the wrong code system is structurally valid — it will pass JSON parsing — but it will fail profile validation and produce incorrect clinical data downstream. Your FHIR architecture must include a multi-layer validation pipeline that runs on every inbound resource before it reaches your data store.

Chapter 11. Production FHIR Monitoring

Standard HTTP monitoring misses most FHIR-specific failure modes. A FHIR server that returns HTTP 200 with an OperationOutcome resource containing errors is succeeding at HTTP and failing at FHIR simultaneously. A Bulk export job that returns 202 Accepted and then silently fails midway through generating output files leaves no visible HTTP error. Your observability stack must understand FHIR semantics — not just HTTP semantics.

FHIR-Specific Metrics to Instrument

• OperationOutcome error rate by resource type and issue code. Track the percentage of FHIR responses containing OperationOutcome resources with severity "error" or "fatal" — broken out by resource type (Patient, Observation, MedicationRequest) and issue code (required, value, invalid). This is your data quality leading indicator.

• FHIR search result-set distribution. Track p50/p95/p99 result counts per search operation type. A sudden shift toward zero-result searches for a parameter that normally returns results indicates a bug in search parameter handling or a source data quality regression — not a legitimate empty result set.

• Bulk export job completion rate and NDJSON file integrity. Track the percentage of $export jobs that complete vs. fail vs. expire. For completed jobs, validate NDJSON file line counts against expected population size. A completed export with 10% fewer lines than expected is a silent data loss event.

• SMART token grant failure rate by error type. Distinguish between invalid_client (key registration issue), invalid_scope (scope not permitted), and server errors. Token grant failures are clinical access failures — they must alert, not just log.

• Terminology validation cache hit rate and error rate. A terminology cache miss on a required code system (LOINC unavailable) that causes validation to fail silently is a production incident. Track terminology service availability separately from FHIR server availability.

Chapter 12. FHIR R5 Migration Readiness

FHIR R5 was published in March 2023. While no major regulatory mandate requires R5 adoption today, Epic's Sandbox, Firely Server, and HAPI FHIR 7.x already expose R5 endpoints. CMS Interoperability rulemaking for 2026+ is expected to reference R5 or R5-aligned IGs. Building R5 readiness into your architecture now costs significantly less than migrating under regulatory pressure later.

Breaking Changes from R4 to R5 That Affect Most Integrations