Interop Service — Service Overview
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The interop-service is the platform's unified interoperability gateway. It consolidates two previously separate modules — fhir-gateway and hl7v2-interop — into a single deployable bounded context that owns all external integration channels: FHIR R4 REST API surface, HL7 v2 MLLP message processing, third-party EMR coexistence adapters, bulk data operations, and terminology gateway routing.
Every clinical service in the platform routes external-facing integrations through here. No other service exposes raw FHIR endpoints to external consumers directly.
2. Bounded Context
| Attribute | Value |
|---|
| DDD context name | interop |
| Source modules | fhir-gateway, hl7v2-interop |
| Licensing category | Core platform (always-on); individual add-on adapters may be gated |
| FHIR profile alignment | US Core 6.1, IPS, Afghanistan FHIR profiles (AFG-Core) |
| HL7 v2 message sets | ADT A01/A03/A04/A08/A40, ORM O01, ORU R01, VXU V04 |
3. Responsibilities
| Responsibility | Detail |
|---|
| FHIR R4 gateway | Single /fhir/R4/* entry point; route/proxy to owning service; consolidated CapabilityStatement |
| FHIR profile enforcement | Validate resources against US Core 6.1, IPS, and AFG-Core profiles on write |
| Bulk data operations | $export (Group/Patient/$export) and $import for large dataset exchange |
| HL7 v2 MLLP listener | Accept ADT/ORM/ORU/VXU messages; parse and persist immutable message log |
| HL7 v2 → FHIR mapping | Translate v2 messages to canonical FHIR resources; POST to owning service |
| HL7 v2 outbound | Serialize FHIR-triggered domain events back to v2 for external LIS/RIS/ADT feeds |
| Third-party EMR adapter | Coexistence pattern for external EMR platforms sharing patient populations |
| Connector management | Per-tenant/facility connector registry; auth config; activation/deactivation |
| OperationOutcome errors | Consistent FHIR error formatting for all FHIR endpoints |
| Tenant + ABAC enforcement | Apply tenantId isolation and resource-level ABAC at the FHIR boundary |
4. Non-Responsibilities
- Clinical data storage (stateless routing; no clinical persistence)
- Clinical domain logic (owned by respective domain services)
- Patient portal access policies (patient-portal-service)
- AI orchestration (ai-gateway-service)
- Terminology data storage (terminology-service)
5. Upstream Dependencies (Consumers of interop-service)
All clinical services use interop-service as the FHIR gateway proxy. Key consumers:
| Service | How it uses interop-service |
|---|
| laboratory-service | Publishes FHIR Observation, DiagnosticReport, Specimen via /fhir/R4/* |
| radiology-service | Publishes FHIR ImagingStudy, DiagnosticReport |
| orders-service | Publishes FHIR ServiceRequest; receives ORM ack from HL7 v2 |
| registration-service | Publishes FHIR Patient, Encounter; receives ADT from HL7 v2 |
| patient-chart-service | Reads FHIR clinical facts (fan-out query) |
| patient-portal-service | Policy-filtered FHIR reads |
| terminology-service | Exposes FHIR terminology operations ($lookup, $expand, $validate-code) |
6. External Integrations
| Integration | Protocol | Direction |
|---|
| External LIS platforms | HL7 v2 ORM/ORU (MLLP) | Bidirectional |
| External ADT sources (HIS, PAS) | HL7 v2 ADT (MLLP) | Inbound |
| Immunization registries | HL7 v2 VXU (MLLP) | Outbound |
| National HMIS | FHIR bulk $export | Outbound |
| Third-party EMR | FHIR R4 REST + AFG-Core profiles | Bidirectional |
| Payer / clearinghouse | X12 EDI (adapter seam) | Outbound |
7. Architecture Diagram
8. Key Architectural Decisions
| Decision | Rationale |
|---|
| Merged fhir-gateway + hl7v2-interop | FHIR mapping is inseparable from HL7 v2 translation; single deployment reduces latency |
| Stateless FHIR routing | No clinical persistence; pure proxy/router; simplifies compliance boundary |
| Per-service ownership routing | Each resource type routes to its owning service; no shared clinical DB |
| ABAC at FHIR boundary | Single enforcement point for external FHIR access; internal service calls bypass |
| Immutable HL7 message log | Non-repudiation; deduplication; compliance requirement |
| US Core 6.1 + IPS + AFG-Core | Multi-audience alignment: international interop (IPS) + US tooling (SMART) + local regulation (AFG) |
9. Source Reconciliation
| Module | Key contributions | Merge decision |
|---|
fhir-gateway | FHIR R4 routing, CapabilityStatement, OperationOutcome, ABAC enforcement, bulk ops | FHIR gateway sub-domain retained |
hl7v2-interop | MLLP listener, message log, ADT/ORM/ORU/VXU mapping, connector registry | HL7 v2 sub-domain co-located; shares connector config with FHIR gateway |
Both sub-domains share a single PostgreSQL schema (interop_connectors, hl7_messages, fhir_routing_rules) and a single NestJS process.