# FHIR Integration Design: [Programme or solution name]

> Solution design for a healthcare interoperability solution built on
> HL7 FHIR and IHE profiles: use cases and actors, FHIR version
> strategy, resources, profiles and implementation guides, terminology,
> IHE ITI profiles (MHD, PIXm, PDQm, IUA, mCSD), SMART App Launch
> authorisation, consent and privacy, Bulk Data Access, coexistence with
> HL7 Version 2 and CDA, conformance testing and operations. Version
> basis: FHIR R5 (5.0.0) as the current published release, FHIR R4
> (4.0.1) as the most widely deployed, FHIR R6 still in ballot; IHE ITI
> Technical Framework Revision 20.2; US Core 9.0.0; SMART App Launch
> 2.2.0; Bulk Data Access 3.0.0. Regulatory touchpoints cover the US
> ONC/ASTP HTI rules and TEFCA, HIPAA and the EU European Health Data
> Space Regulation (EU) 2025/327. Replace every `[bracketed]` value and
> every row marked *Example*. This is a documentation format, not legal
> advice.

<!--
Guidance: How to use this template
- Write one design per interoperability solution (for example a
  regional document sharing network, a patient access API, a payer
  data exchange or an EHR integration hub).
- Fill section 1 (use cases and actors) and section 3 (FHIR version
  and IG strategy) first. Choosing a FHIR release and implementation
  guides fixes what every partner must build.
- Every interface in section 9 names its FHIR version, profile or IHE
  transaction, security model and test evidence.
- Clinical document content (discharge summaries, referral letters)
  belongs in the clinical templates: Discharge Summary
  (`healthcare/discharge-summary`), Referral Letter
  (`healthcare/referral-letter`), Care Plan (`healthcare/care-plan`).
- HIPAA safeguards are designed in HIPAA Security Solution Design
  (`compliance/hipaa-security-solution-design`); general integration
  patterns in Integration Design (`architecture/integration-design`);
  API platform choices in API Management Platform Design
  (`architecture/api-management-platform-design`); consumer identity in
  CIAM Solution Design (`security/ciam-solution-design`).
- Laws are cited by article or section number and paraphrased. Check
  the consolidated texts and current rules before relying on dates.
-->

## Document control

<!-- Guidance: Identify the solution, its partners and the regulatory regimes in scope. A change of FHIR release, a new mandatory implementation guide or a new jurisdiction is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [FHIR-INT-001] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@interoperability-architect] |
| Approvers/reviewers | [@clinical-safety-officer], [@privacy-officer], [@security-architect], [@ehr-integration-lead], [@terminology-lead] |
| Organisation and partners | [Health system, HIE, payer, vendor partners] |
| Jurisdictions | [US / EU member state / UK / other] |
| FHIR release and IGs | [R4 4.0.1 with US Core 9.0.0 / R5 5.0.0 with national IG / other] |
| IHE profiles | [MHD, PIXm, PDQm, IUA, mCSD, others], ITI TF Revision [20.2] |
| Regulatory regimes | [HIPAA, HTI rules, TEFCA, EHDS, GDPR, national law] |
| Clinical safety | [Clinical risk management standard and hazard log reference] |
| Classification | [Confidential] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Clinical safety officer | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Privacy officer or DPO | [@name] | [Decision] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Architecture board | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved for regional document sharing pilot |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added bulk export for population health; US Core upgraded |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Use cases and actors](#1-use-cases-and-actors)
2. [Requirements](#2-requirements)
3. [FHIR version and implementation guide strategy](#3-fhir-version-and-implementation-guide-strategy)
4. [Resources and profiles](#4-resources-and-profiles)
5. [Terminology](#5-terminology)
6. [IHE profiles and document sharing](#6-ihe-profiles-and-document-sharing)
7. [Authorisation and identity (SMART, IUA)](#7-authorisation-and-identity-smart-iua)
8. [Consent, privacy and regulatory touchpoints](#8-consent-privacy-and-regulatory-touchpoints)
9. [Interface catalogue and integration architecture](#9-interface-catalogue-and-integration-architecture)
10. [Bulk data and analytics](#10-bulk-data-and-analytics)
11. [HL7 Version 2 and CDA coexistence](#11-hl7-version-2-and-cda-coexistence)
12. [Conformance testing and clinical safety](#12-conformance-testing-and-clinical-safety)
13. [Operations, risks and decisions](#13-operations-risks-and-decisions)
14. [Glossary and references](#14-glossary-and-references)

## 1. Use cases and actors

<!-- Guidance: Describe who exchanges what clinical information, when and why. Questions: which care settings, which partners, which patients? What happens today (fax, portal, HL7 v2 feeds)? Pitfall: starting from FHIR resources instead of clinical workflows, which produces APIs that nobody calls. -->

### 1.1 Use cases

| ID | Use case | Actors | Trigger | Current method | Volume |
|---|---|---|---|---|---|
| UC-001 *(Example)* | Clinician at an emergency department retrieves documents from other hospitals | ED clinician, document registry, other hospitals | Patient registration | Phone and fax | [2,000 queries a day] |
| UC-002 *(Example)* | Patient uses a third-party app to access their records | Patient, app, EHR FHIR server | Patient consent | Portal download | [n] |
| UC-003 *(Example)* | Hospital publishes discharge summaries for the GP | Hospital EHR, document repository, GP system | Discharge | Letter by post or HL7 v2 | [n] |
| UC-004 *(Example)* | Population health team receives monthly bulk extracts | Analytics platform, EHR | Schedule | Database extract | [n] patients |
| UC-005 *(Example)* | Directory lookup of practitioners and services | Any participant, care services directory | Referral | Spreadsheet | [n] |
| [UC-NNN] | [Use case] | [Actors] | [Trigger] | [Current] | [Volume] |

### 1.2 Actor and system context

The diagram places every actor from section 1.1 around the platform components described in section 9.2. Internal feeds stay on HL7 Version 2 through the integration engine; external partners reach FHIR and IHE endpoints only through the gateway.

```mermaid
flowchart LR
    APP["Patient and clinician apps (SMART)"] --> GW["API gateway and authorisation server"]
    GW --> FHIR["EHR FHIR server"]
    GW --> REG["Document registry and repository (MHD)"]
    GW --> MPI["Patient identity cross-reference (PIXm, PDQm)"]
    GW --> DIR["Care services directory (mCSD)"]
    EHR["EHR and departmental systems"] -- "HL7 v2 ADT, ORU" --> ENG["Integration engine"]
    ENG --> FHIR
    ENG --> MPI
    ENG --> REG
    FHIR -- "Bulk export" --> ANA["Analytics platform"]
    TERM["Terminology server"] --- FHIR
    TERM --- ENG
```

## 2. Requirements

<!-- Guidance: Turn use cases into verifiable requirements, including clinical safety, privacy and performance. Pitfall: a requirement that says "FHIR compliant" without naming the release, profile and capability statement. -->

### 2.1 Functional requirements

| ID | Requirement | Use case | Acceptance criterion |
|---|---|---|---|
| FR-001 *(Example)* | Find documents for a patient across participating hospitals | UC-001 | MHD Find Document References returns results from all registries in under [3 seconds] |
| FR-002 *(Example)* | Resolve the patient's identifiers across organisations | UC-001, UC-003 | PIXm query returns the correct cross-referenced identifiers in test set |
| FR-003 *(Example)* | Patient-authorised app reads clinical data defined by the national core IG | UC-002 | App passes the IG test kit read scenarios |
| FR-004 *(Example)* | Discharge summary published within [1 hour] of signing | UC-003 | Document available to GP system in 99 % of cases |
| FR-005 *(Example)* | Monthly bulk export of defined resource types for a patient group | UC-004 | Export of [n] patients completes within [6 hours] |
| [FR-NNN] | [Requirement] | [UC] | [Criterion] |

### 2.2 Quality attributes

| ID | Attribute | Requirement | Verification |
|---|---|---|---|
| NFR-001 *(Example)* | Availability | Clinical query APIs 99.9 % monthly | Monitoring |
| NFR-002 *(Example)* | Latency | Read of a single resource under [500 ms] at the 95th percentile | Load test |
| NFR-003 *(Example)* | Security | All access authorised with scoped tokens and audited | Security test, audit review |
| NFR-004 *(Example)* | Data integrity | No clinical data altered in transformation; codes preserved | Round-trip and terminology tests |
| NFR-005 *(Example)* | Clinical safety | Hazards assessed and controls verified before go-live | Clinical safety case |
| [NFR-NNN] | [Attribute] | [Requirement] | [Verification] |

### 2.3 Volumes and sizing

Size the platform from the use case volumes and write the consequence of each number. The figures are a worked example for a regional network.

| ID | Quantity | Example value | Derivation | Design consequence |
|---|---|---|---|---|
| VOL-001 *(Example)* | UC-001 document queries a day | 2,000 | Emergency department attendances that need outside records | Input to VOL-002 |
| VOL-002 *(Example)* | API calls per query | 6 | One token request, one PIXm query, one find, three retrieves on average | 12,000 calls a day from UC-001 |
| VOL-003 *(Example)* | Peak hour calls | 1,440 | 12 % of 12,000 in the busiest hour | Under one call a second: latency (NFR-002) and registry fan-out, not throughput, drive the design |
| VOL-004 *(Example)* | Bulk export cohort | 500,000 patients at 400 resources each | Population health cohort definition | 200 million resources a month |
| VOL-005 *(Example)* | Bulk export size and rate | About 300 GB at 1.5 KB per resource | 200 million times 1.5 KB | Inside the 6-hour window of FR-005: about 9,260 resources a second and 50 GB an hour; export from a read replica with parallel workers, never from the live EHR |
| VOL-006 *(Example)* | Patient identity records in the MPI | 3,000,000 across 12 organisations | Sum of active patient registers | Matching index and review queue sizing in section 6.3 |

Recompute the derived values whenever an input changes: VOL-002 times VOL-001 gives the daily call count, and the resource count divided by 21,600 seconds gives the export rate.

## 3. FHIR version and implementation guide strategy

<!-- Guidance: Choose the FHIR release for each interface and the implementation guides (IGs) that constrain it. Questions: what release do your partners and regulators require? Is there a national core IG? Pitfall: choosing the newest release when every partner and certified product supports only R4. -->

### 3.1 FHIR release status (checked at hl7.org, October 2026)

| Release | Version | Status | Use in this design |
|---|---|---|---|
| R4 | 4.0.1 (published 2019-10-30) | First release with normative content; the most widely implemented release and the base for most national IGs | [*Example:* All partner-facing APIs] |
| R4B | 4.3.0 (2022-05-28) | Interim release, limited adoption | [Not used] |
| R5 | 5.0.0 (2023-03-26) | Current published release | [*Example:* Internal subscriptions pilot only] |
| R6 | 6.0.0-ballot5 (2026-07-17) and 6.0.0-snapshot1 | In ballot, not final; do not build production interfaces on it | [Monitor] |

Version rules:

- Fix one release per interface and declare it in the server CapabilityStatement (`fhirVersion`) and in the IG dependency list.
- Where partners use different releases, convert at a single gateway, never in each client; list each conversion and its data loss risk in section 3.3.
- Track the R6 ballot and the readiness of your IGs; plan a migration only when the national IGs and certified products move.

### 3.2 Implementation guides

| IG | Version | Base release | Why | Mandatory for |
|---|---|---|---|---|
| US Core *(Example, US)* | 9.0.0 (2026-05-31); check the version required by the ONC certification program and SVAP | R4 4.0.1 | Patient access and certified API baseline | UC-002, UC-003 |
| International Patient Summary *(Example)* | [Version] | R4 | Cross-border summary content | UC-003 |
| National core IG *(Example, EU member state)* | [Version] | [Release] | National profiles and terminology bindings | All |
| IHE ITI profiles | Section 6 | R4 | Document sharing, identity, directory | UC-001, UC-005 |
| SMART App Launch | 2.2.0 (2024-04-30) | R4 | App authorisation | UC-002 |
| Bulk Data Access | 3.0.0, STU 3 (2025-12-11); 4.0.0 in ballot | R4 | Population export | UC-004 |
| [IG] | [Version] | [Release] | [Why] | [Use cases] |

### 3.3 Version conversion register

| ID | From | To | Resources | Known loss or change | Mitigation | Owner |
|---|---|---|---|---|---|---|
| CNV-001 *(Example)* | R5 internal subscription events | R4 partner notifications | SubscriptionStatus, Encounter | R5 topic-based fields carried only through the R4 Subscriptions backport extensions | Partners use the backport IG; conversion tests per release | @platform-team |
| CNV-002 *(Example)* | R4 | R5 internal pilot | Observation, Patient | Renamed and moved elements handled by version conversion maps; extensions for elements absent in R4 | Use the HL7 cross-version extensions; reject on unmapped required elements | @interoperability-architect |
| [CNV-NNN] | [From] | [To] | [Resources] | [Loss] | [Mitigation] | [@owner] |

Never convert silently: record the source version in Provenance or a meta tag so that a downstream consumer can tell converted content from native content.

## 4. Resources and profiles

<!-- Guidance: List the FHIR resources you exchange, the profile that constrains each, and the must-support rules. Pitfall: local profiles that duplicate national ones with small differences, forcing partners to implement both. -->

| Resource | Profile (canonical URL) | Interactions | Must-support decisions | Owner |
|---|---|---|---|---|
| Patient *(Example)* | [National core Patient] | read, search by identifier, name, birthdate | Identifier with system URI required; no free-text only names | @ehr-integration-lead |
| Encounter *(Example)* | [Core Encounter] | read, search by patient and date | Class and period required | @ehr-integration-lead |
| Observation (laboratory) *(Example)* | [Core laboratory result] | read, search by patient, category, code, date | LOINC code required, UCUM units | @lab-it |
| Condition *(Example)* | [Core Condition] | read, search | SNOMED CT or ICD-10 coding; clinical status required | @ehr-integration-lead |
| MedicationRequest *(Example)* | [Core MedicationRequest] | read, search | National medication terminology code | @pharmacy-it |
| DocumentReference *(Example)* | IHE MHD profiles | create through ITI-105 or ITI-65, search | Author, type, practice setting, confidentiality | @document-sharing-lead |
| Practitioner, Organization, Location, HealthcareService *(Example)* | IHE mCSD profiles | search | Active status, identifiers | @directory-lead |
| Provenance, AuditEvent *(Example)* | [Core Provenance], IHE BALP | create, search | Who, when, source system | @security-architect |
| [Resource] | [Profile] | [Interactions] | [Decisions] | [@owner] |

Profile governance:

- Publish local profiles in a FHIR IG built with the HL7 IG Publisher, with examples and a version per release.
- Derive local profiles from the national core profiles; record each additional constraint and extension with a reason.
- Run the FHIR validator against every example and against sampled production payloads.

## 5. Terminology

<!-- Guidance: Bind coded elements to code systems and value sets, and decide where terminology services run. Questions: which licences do you hold (SNOMED CT affiliate licence, LOINC terms of use)? Which national editions apply? Pitfall: mapping codes in the integration engine with hand-written tables that drift from the source code systems. -->

| Domain | Code system | Edition or version | Binding strength | Source of truth |
|---|---|---|---|---|
| Problems and diagnoses *(Example)* | SNOMED CT; ICD-10 (national modification) for billing; ICD-11 where adopted | [National edition, release date] | Extensible | Terminology server |
| Laboratory tests *(Example)* | LOINC | [Version] | Required for results | Terminology server |
| Units *(Example)* | UCUM | Current | Required | Terminology server |
| Medications *(Example)* | [RxNorm / national medicinal product dictionary] | [Release] | Required | Terminology server |
| Document types *(Example)* | LOINC document ontology or national value set | [Version] | Required in MHD metadata | Registry configuration |
| Administrative codes *(Example)* | FHIR core code systems | Release in section 3 | Required | IG |
| [Domain] | [System] | [Version] | [Strength] | [Source] |

Terminology services:

- Run a FHIR terminology server exposing `$expand`, `$validate-code`, `$lookup` and `$translate` for every system in the table.
- Maintain maps (ConceptMap) for local codes, with clinical review of every map and a version per release.
- Load new code system releases on a schedule, test value set expansions and announce changes to partners.

## 6. IHE profiles and document sharing

<!-- Guidance: Name the IHE ITI profiles you implement, the actors each system plays and the options chosen. IHE ITI profiles are published at profiles.ihe.net; the Technical Framework is at Revision 20.2 (November 2025) and FHIR-based profiles carry their own versions. Pitfall: claiming a profile without listing actors and transactions, which tells partners nothing. -->

### 6.1 Profiles and actors

| Profile | Version checked | Actor played by this solution | Transactions (IHE numbers) | Partners |
|---|---|---|---|---|
| MHD, Mobile access to Health Documents | 4.2.5 | Document Responder, Document Recipient | ITI-66 find lists, ITI-67 find document references, ITI-68 retrieve, ITI-65 or ITI-105 publish | Hospitals, GP systems |
| PIXm, Patient Identifier Cross-reference for Mobile | 3.1.0 | Patient Identifier Cross-reference Manager | ITI-83 query, ITI-104 feed | All participants |
| PDQm, Patient Demographics Query for Mobile | 3.2.0 | Patient Demographics Supplier | ITI-78 query (and ITI-119 match where supported) | All participants |
| IUA, Internet User Authorization | ITI TF Rev 20.2, Volume 1 | Authorization Server, Resource Server | ITI-71 get access token, ITI-72 incorporate token, ITI-102 introspect | All participants |
| mCSD, Mobile Care Services Discovery | 4.0.0 | Care Services Selective Supplier | ITI-90 find matching care services | Directory consumers |
| BALP, Basic Audit Log Patterns; ATNA *(Example)* | [Version] | Audit Record Repository | ITI-20 record audit event | Security operations |
| [Profile] | [Version] | [Actor] | [Transactions] | [Partners] |

Check every transaction number against the current profile page before publishing this design to partners.

### 6.2 Document query and retrieve sequence

The sequence shows UC-001: an emergency clinician's system resolves the patient's identifiers, finds documents and retrieves one, with a token checked at each step.

```mermaid
sequenceDiagram
    participant CL as ED clinician system
    participant AS as Authorization server (IUA)
    participant MPI as Identity cross-reference (PIXm)
    participant REG as Document responder (MHD)
    CL->>AS: Request token with purpose of use (ITI-71)
    AS-->>CL: Access token with scopes
    CL->>MPI: Query cross-referenced identifiers (ITI-83)
    MPI-->>CL: Identifiers in each affinity domain
    CL->>REG: Find document references (ITI-67)
    REG-->>CL: Bundle of DocumentReference
    CL->>REG: Retrieve document (ITI-68)
    REG-->>CL: Document content
    REG->>REG: Record audit event
```

### 6.3 Patient identity matching

Patient matching is the main clinical safety risk in document sharing (HAZ-001). Design it explicitly:

| Item | Decision |
|---|---|
| Matching approach *(Example)* | Deterministic match on a national patient identifier where present; otherwise probabilistic matching on name, birth date, sex, address and phone with weighted scores |
| Thresholds *(Example)* | Score at or above [upper threshold]: automatic link; between [lower] and [upper]: manual review queue; below [lower]: no link |
| Review queue *(Example)* | Data stewards review queued pairs within [2 working days]; decisions are logged and feed threshold tuning |
| Unmerge *(Example)* | A wrong link can be undone; consumers are notified through the identity feed (ITI-104) and cached cross-references are invalidated |
| Query behaviour *(Example)* | PDQm returns candidates with a match grade; clinician systems show demographics for confirmation before displaying documents |
| Measures *(Example)* | False match rate and false non-match rate measured on the TST-005 set each release |

### 6.4 Relationship with XDS and cross-community exchange

| Item | Decision |
|---|---|
| Existing XDS.b infrastructure *(Example)* | Keep registry and repository; expose MHD as a facade (MHDS pattern or gateway) |
| Cross-community query *(Example)* | XCA gateways for national network; MHD for apps and smaller providers |
| Document formats *(Example)* | CDA documents kept as-is; new documents as FHIR Bundle (type document) where the national IG defines them |
| Metadata rules *(Example)* | Class, type, practice setting, facility type and confidentiality codes from the value sets in section 5 |

## 7. Authorisation and identity (SMART, IUA)

<!-- Guidance: Define how apps and systems obtain tokens, what scopes mean, and how patient and practitioner identities are proven. SMART App Launch 2.x defines launch contexts and scopes on OAuth 2.0 and OpenID Connect; Backend Services covers system-to-system access. Pitfall: broad system scopes (for example all resources) issued to every partner because fine-grained scopes were never designed. -->

| Item | Decision |
|---|---|
| Patient-facing apps *(Example)* | SMART App Launch 2.2.0 standalone launch, PKCE required, the launch/patient scope for patient context, resource scopes in SMART v2 syntax (for example `patient/Observation.rs`) |
| Clinician apps in the EHR *(Example)* | SMART EHR launch with `launch` context and `openid fhirUser` |
| System to system *(Example)* | SMART Backend Services with asymmetric client authentication (private key JWT) and `system/` scopes per partner |
| Cross-organisation document sharing *(Example)* | IUA tokens carrying subject, organisation and purpose of use |
| Identity proofing for patients *(Example)* | [National digital identity / portal proofing at NIST SP 800-63-4 IAL2 or national level] |
| Token lifetime and refresh *(Example)* | Access tokens [5 minutes] for system clients, [1 hour] for apps; refresh tokens only with `offline_access` and patient approval |
| App registration and vetting *(Example)* | Dynamic or manual registration with terms of use; information blocking rules considered before refusing an app (US) |
| Discovery *(Example)* | `.well-known/smart-configuration` published on each FHIR base URL |

Detail the identity provider design in CIAM Solution Design (`security/ciam-solution-design`) or IAM Solution Design (`security/iam-solution-design`).

## 8. Consent, privacy and regulatory touchpoints

<!-- Guidance: Show how consent and legal rules are enforced in the exchange, and list the regulatory obligations that shape the design. Paraphrase; cite sections and articles; check current texts. Pitfall: recording consent as a FHIR Consent resource but never evaluating it in the access decision. -->

### 8.1 Consent and access control

| Item | Decision |
|---|---|
| Consent model *(Example)* | Opt-out for direct care sharing within the region; explicit opt-in for research use |
| Representation *(Example)* | FHIR Consent resources in the consent registry; [IHE Privacy Consent on FHIR (PCF)] where adopted |
| Enforcement point *(Example)* | Access decision in the gateway combines token scopes, purpose of use, consent and confidentiality labels |
| Sensitive data *(Example)* | Security labels on resources (for example restricted categories under national law) filter results |
| Break the glass *(Example)* | Emergency access with reason, extra audit and review within [24 hours] |
| Patient access to logs *(Example)* | Patients can see who accessed their records through the portal |

### 8.2 Regulatory touchpoints

| Regime | Requirement (paraphrased) | Design response | Check |
|---|---|---|---|
| US HIPAA Privacy and Security Rules (45 CFR Parts 160 and 164) | Protect electronic protected health information with administrative, physical and technical safeguards; minimum necessary use | HIPAA Security Solution Design (`compliance/hipaa-security-solution-design`) | Current HHS rules and any final Security Rule update |
| US ONC/ASTP HTI rules | HTI-1 (Federal Register January 2024): certification updates, USCDI v3 baseline from 2026-01-01, decision support transparency, information blocking; HTI-2 (December 2024): TEFCA; HTI-4 (August 2025): electronic prescribing and prior authorisation; HTI-5 proposed deregulatory changes | Certified API conformance, US Core version per program requirements | healthit.gov HTI rules page for final status |
| US TEFCA | Nationwide exchange through Qualified Health Information Networks under the Common Agreement; FHIR-based exchange expanding | Connect through a QHIN or participant; map exchange purposes to section 8.1 | Current Common Agreement and SOPs |
| EU European Health Data Space, Regulation (EU) 2025/327 | In force 26 March 2025; applies generally from 26 March 2027 (Article 105); primary-use exchange of the first priority categories (patient summaries, ePrescriptions and eDispensations) from March 2029 and of the second group (medical images, laboratory results, hospital discharge reports) from March 2031; European EHR exchange format; requirements for EHR systems; secondary use through health data access bodies, largely from March 2029 | Map documents to the European exchange format; plan EHR system conformity | Consolidated text on EUR-Lex (Article 14 priority categories, Article 105 application) and implementing acts due by March 2027 |
| EU GDPR (Regulation (EU) 2016/679) | Health data is a special category (Article 9); DPIA for large-scale processing (Article 35) | DPIA (`compliance/dpia`) | Consolidated text and national law |
| [Regime] | [Requirement] | [Response] | [Check] |

## 9. Interface catalogue and integration architecture

<!-- Guidance: List every interface with its standard and security model, and show the platform components. Pitfall: an integration engine that becomes a second clinical record because it stores transformed copies indefinitely. -->

### 9.1 Interface catalogue

| ID | Interface | Standard | FHIR release or v2 version | Direction | Security | Partners | Status |
|---|---|---|---|---|---|---|---|
| FX-001 *(Example)* | Patient access API | US Core or national core IG, SMART | R4 4.0.1 | Inbound reads | SMART App Launch | Any registered app | Live |
| FX-002 *(Example)* | Document query and retrieve | MHD, PIXm | R4 | Inbound | IUA | Regional hospitals | Pilot |
| FX-003 *(Example)* | Discharge summary publication | MHD ITI-65 | R4 | Outbound | Backend Services, mutual TLS | GP systems | Build |
| FX-004 *(Example)* | ADT feed from EHR | HL7 v2 ADT | v2.5.1 | Inbound to engine | VPN, mutual TLS | EHR | Live |
| FX-005 *(Example)* | Population export | Bulk Data Access | R4 | Outbound | Backend Services | Analytics platform | Build |
| FX-006 *(Example)* | Directory | mCSD | R4 | Inbound queries | IUA | All participants | Build |
| [FX-NNN] | [Interface] | [Standard] | [Version] | [Direction] | [Security] | [Partners] | [Status] |

### 9.2 Platform components

| Component | Responsibility | Product | Hosting | Owner |
|---|---|---|---|---|
| API gateway *(Example)* | Routing, rate limits, token validation, version conversion | [Product] | [Region] | @platform-team |
| Authorisation server *(Example)* | SMART and IUA tokens, client registry | [Product] | [Region] | @security-architect |
| FHIR server or facade *(Example)* | Serve profiles over EHR data | [Product] | [Region] | @ehr-integration-lead |
| Integration engine *(Example)* | HL7 v2 and CDA ingestion and transformation | [Product] | [Region] | @integration-team |
| Master patient index *(Example)* | Identity matching and cross-reference | [Product] | [Region] | @mpi-lead |
| Terminology server *(Example)* | Section 5 services | [Product] | [Region] | @terminology-lead |
| Audit repository *(Example)* | AuditEvent store, access reports | [Product] | [Region] | @security-architect |

Design rules:

- Store transformed copies only where a use case needs them, with a retention period; otherwise transform on read.
- Use FHIR Subscriptions (topic-based in R5, or the R4 backport IG) for event notification instead of polling where partners support it.
- Apply rate limits per client and protect EHR back ends with caching and query limits on expensive searches.

### 9.3 API behaviour rules

| ID | Rule |
|---|---|
| API-001 *(Example)* | Every error returns an OperationOutcome with a severity, a code and a human-readable diagnostic that contains no patient data |
| API-002 *(Example)* | Searches page results with a default `_count` of [50] and a maximum of [200]; clients follow the `next` link and never build page URLs themselves |
| API-003 *(Example)* | Updates use version-aware writes (ETag with If-Match) so that two writers cannot overwrite each other |
| API-004 *(Example)* | Creates from partner systems are conditional on a business identifier to stop duplicates on retry |
| API-005 *(Example)* | `_include` and `_revinclude` are limited to the combinations listed in the CapabilityStatement |
| API-006 *(Example)* | Every read and search writes an AuditEvent with the client, the user, the patient and the purpose of use |
| API-007 *(Example)* | Deprecated profile versions stay available for [12 months] after announcement, with a deprecation header |
| [API-NNN] | [Rule] |

## 10. Bulk data and analytics

<!-- Guidance: Design population-level export with the FHIR Bulk Data Access IG (the $export operation, asynchronous request pattern and NDJSON output). Pitfall: running bulk export against the live EHR database during clinic hours. -->

| Item | Decision |
|---|---|
| Export level *(Example)* | Group-level `$export` for defined cohorts; no system-level export to external parties |
| Resource types *(Example)* | Patient, Encounter, Condition, Observation, MedicationRequest, Procedure |
| Incremental export *(Example)* | `_since` parameter for monthly deltas |
| Output and storage *(Example)* | NDJSON files in an encrypted bucket with short-lived signed URLs; deleted after [7 days] |
| Scheduling *(Example)* | Off-peak window [01:00 to 05:00] against a read replica |
| Privacy *(Example)* | De-identification or pseudonymisation before analytics where the purpose allows; purpose recorded |
| Downstream *(Example)* | Data Platform Architecture (`architecture/data-platform-architecture`) |

## 11. HL7 Version 2 and CDA coexistence

<!-- Guidance: Most hospitals run HL7 v2 feeds for admissions, orders and results and CDA for documents. Decide which flows stay on v2, which move to FHIR and how mappings are governed. The HL7 Version 2 to FHIR IG gives mapping guidance. Pitfall: a big-bang replacement of v2 feeds that work. -->

| Flow | Today | Target | Mapping | Owner |
|---|---|---|---|---|
| Admissions and transfers *(Example)* | HL7 v2 ADT A01, A02, A03, A08 | Keep v2 internally; publish FHIR Encounter and Patient | v2 to FHIR maps in the engine, versioned | @integration-team |
| Laboratory results *(Example)* | HL7 v2 ORU R01 | FHIR Observation and DiagnosticReport for external consumers | Map OBX to Observation with LOINC and UCUM | @lab-it |
| Orders *(Example)* | HL7 v2 ORM or OML | Unchanged | None | @integration-team |
| Discharge documents *(Example)* | CDA documents by post or v2 MDM | MHD publication of CDA, FHIR documents later | Metadata mapping only | @document-sharing-lead |
| [Flow] | [Today] | [Target] | [Mapping] | [@owner] |

Mapping governance: every map has a specification, test messages with expected FHIR output, clinical review for coded content and a version tied to the profile version.

## 12. Conformance testing and clinical safety

<!-- Guidance: Plan conformance tests with community tools, partner connectathon-style testing and clinical safety assurance. Pitfall: testing only the happy path, while clinical risk sits in missing, duplicated or mismatched patient data. -->

### 12.1 Tests

| ID | Test | Tool or method | Pass criterion | Evidence |
|---|---|---|---|---|
| TST-001 *(Example)* | Profile validation | FHIR validator with IG packages | Zero errors on examples and sampled payloads | Validation report |
| TST-002 *(Example)* | Core IG API tests | [ONC Inferno test kit / national test kit] | All required tests pass | Test kit report |
| TST-003 *(Example)* | IHE profile tests | IHE Gazelle tools, IHE Connectathon | Pass for each actor and transaction in section 6.1 | Connectathon results |
| TST-004 *(Example)* | SMART authorisation | SMART test suite or test kit | Scopes and launch contexts behave as specified | Test report |
| TST-005 *(Example)* | Patient matching | Curated test set with known duplicates and twins | False match rate under [target] | Matching report |
| TST-006 *(Example)* | Bulk export load | Export of [n] patients | Completes within FR-005 target | Load test |
| TST-007 *(Example)* | Security | Penetration test of gateway and authorisation server | No open high findings | Pentest report |
| TST-008 *(Example)* | Load and availability | Load test at 3 times VOL-003; availability monitoring | NFR-002 latency met; NFR-001 met over 30 days | Load test and monitoring reports |
| TST-009 *(Example)* | v2 and CDA mapping round trip | Test message sets per map in section 11 | Codes, units and values unchanged | Mapping test report |
| TST-010 *(Example)* | Discharge publication timing | End-to-end test from signing to GP retrieval | FR-004 target met in 99 % of runs | Scenario test record |
| TST-011 *(Example)* | Clinical safety case review | Hazard log walk-through with clinicians | Every HAZ control verified and residual risk accepted | Clinical safety case report |
| [TST-NNN] | [Test] | [Tool] | [Criterion] | [Evidence] |

### 12.2 Clinical safety

| Hazard ID | Hazard | Cause | Control | Verification |
|---|---|---|---|---|
| HAZ-001 *(Example)* | Wrong patient's documents shown | Identifier mismatch in cross-reference | Matching thresholds and review queue (section 6.3), demographic confirmation in UI | TST-005 |
| HAZ-002 *(Example)* | Result shown with wrong unit | Unit lost in v2 to FHIR mapping | UCUM required, mapping tests | TST-001, TST-009 |
| HAZ-003 *(Example)* | Missing documents assumed complete | Registry unavailable | UI shows which sources responded | TST-003 |
| [HAZ-NNN] | [Hazard] | [Cause] | [Control] | [Verification] |

### 12.3 Traceability

| Requirement | Design element | Test |
|---|---|---|
| FR-001 *(Example)* | FX-002, section 6 | TST-003 |
| FR-002 *(Example)* | PIXm, section 6.1 | TST-003, TST-005 |
| FR-003 *(Example)* | FX-001, section 7 | TST-002, TST-004 |
| FR-004 *(Example)* | FX-003 | TST-010 |
| FR-005 *(Example)* | FX-005, section 10 | TST-006 |
| NFR-001, NFR-002 *(Example)* | Section 9.2, VOL-003 | TST-008 |
| NFR-003 *(Example)* | Sections 7 and 8, API-006 | TST-004, TST-007 |
| NFR-004 *(Example)* | Section 11, CNV register | TST-001, TST-009 |
| NFR-005 *(Example)* | Section 12.2 | TST-011 |
| [ID] | [Element] | [Test] |

## 13. Operations, risks and decisions

<!-- Guidance: Define who runs the platform, how partners are onboarded and how incidents with clinical impact are handled. Pitfall: no partner onboarding process, so each new connection is a project. -->

### 13.1 Operations

| Activity | Approach | Owner |
|---|---|---|
| Partner onboarding *(Example)* | Registration, test kit evidence, agreement signed, production credentials | @interoperability-architect |
| Monitoring *(Example)* | Per-interface availability, latency, error rates, token failures | @platform-team |
| Clinical incident handling *(Example)* | Incidents with patient safety impact escalated to the clinical safety officer within [1 hour] | @clinical-safety-officer |
| Release management *(Example)* | IG and profile releases announced [60 days] ahead with a sandbox | @interoperability-architect |
| Audit review *(Example)* | Monthly access pattern review; patient access log requests answered within [n days] | @privacy-officer |

### 13.2 Risks

| ID | Risk | Likelihood | Impact | Response | Owner |
|---|---|---|---|---|---|
| RSK-001 *(Example)* | Partners on different FHIR releases | High | Medium | Single conversion gateway, R4 as exchange baseline, CNV register (section 3.3) | @interoperability-architect |
| RSK-002 *(Example)* | Patient matching errors | Medium | High | HAZ-001 controls, data quality programme | @mpi-lead |
| RSK-003 *(Example)* | Regulatory requirement versions change mid-programme | Medium | Medium | Quarterly regulatory review, section 8.2 | @compliance-lead |
| RSK-004 *(Example)* | Terminology licence gaps for partners | Low | Medium | Licence check during onboarding | @terminology-lead |
| [RSK-NNN] | [Risk] | [L / M / H] | [L / M / H] | [Response] | [@owner] |

### 13.3 Decisions

| ID | Decision | Alternatives | Date |
|---|---|---|---|
| DEC-001 *(Example)* | R4 4.0.1 as the exchange baseline | R5 for new interfaces | YYYY-MM-DD |
| DEC-002 *(Example)* | MHD facade on existing XDS infrastructure | Replace XDS | YYYY-MM-DD |
| DEC-003 *(Example)* | Keep HL7 v2 internally, FHIR externally | Convert all feeds | YYYY-MM-DD |
| [DEC-NNN] | [Decision] | [Alternatives] | YYYY-MM-DD |

Record each decision in full in an Architecture Decision Log (`architecture/architecture-decision-log`).

## 14. Glossary and references

<!-- Guidance: Define interoperability terms for non-specialist readers and list the versions used with the date checked. -->

### 14.1 Glossary

| Term | Meaning |
|---|---|
| FHIR | Fast Healthcare Interoperability Resources: HL7 standard for exchanging healthcare data as resources over REST and messaging |
| Implementation guide (IG) | Published set of profiles, extensions, terminology bindings and rules for a use case or jurisdiction |
| Profile | Constraint on a FHIR resource for a specific use |
| Must support | IG flag that a system must be able to handle an element as the IG defines |
| IHE actor | System role in an IHE profile, with the transactions it must support |
| SMART App Launch | HL7 IG for authorising apps to FHIR servers on OAuth 2.0 and OpenID Connect |
| NDJSON | Newline-delimited JSON, the output format of bulk export |
| QHIN | Qualified Health Information Network under TEFCA |
| MPI | Master patient index |

### 14.2 References

| Reference | Version or date | Use |
|---|---|---|
| HL7 FHIR R4, hl7.org/fhir/R4 | 4.0.1, 2019-10-30 | Exchange baseline |
| HL7 FHIR R5, hl7.org/fhir/R5 | 5.0.0, 2023-03-26 | Current release |
| HL7 FHIR R6 ballot, hl7.org/fhir/6.0.0-ballot5 | 2026-07-17, not final | Watch list |
| US Core IG, hl7.org/fhir/us/core | 9.0.0, 2026-05-31 | US core profiles |
| SMART App Launch IG, hl7.org/fhir/smart-app-launch | 2.2.0, 2024-04-30 | Authorisation |
| Bulk Data Access IG, hl7.org/fhir/uv/bulkdata | 3.0.0 STU 3, 2025-12-11 | Population export |
| IHE ITI Technical Framework, profiles.ihe.net/ITI/TF | Revision 20.2, 2025-11-11 | IUA and transactions |
| IHE MHD, PIXm, PDQm, mCSD, profiles.ihe.net/ITI | 4.2.5, 3.1.0, 3.2.0, 4.0.0 | Section 6 |
| ONC/ASTP HTI rules, healthit.gov/regulations/hti-rules | Page updated 2026-04-29 | Section 8.2 |
| Regulation (EU) 2025/327 (European Health Data Space) | OJ 2025-03-05, in force 2025-03-26 | Section 8.2 |
| SNOMED CT, LOINC, UCUM, ICD-10, ICD-11 | Editions per section 5 | Terminology |

## Standard and licence note

Based on HL7 FHIR R4 (4.0.1) and R5 (5.0.0) and the HL7 implementation guides US Core 9.0.0, SMART App Launch 2.2.0 and Bulk Data Access 3.0.0 (HL7 FHIR content is published under the Creative Commons CC0 public domain dedication; HL7 and FHIR are registered trademarks of Health Level Seven International), the IHE ITI Technical Framework Revision 20.2 and IHE FHIR profiles (cited by name, version and transaction number), and public law and regulation (US HIPAA rules, ONC/ASTP HTI rules and TEFCA, Regulation (EU) 2025/327, Regulation (EU) 2016/679). Terminologies such as SNOMED CT and LOINC are named only and need their own licences. All text is original and no specification or legal text is reproduced. Check the current official versions, the R6 status and the consolidated legal texts before use. This is a documentation format, not legal advice. Template licence: MIT.