Skip to main content

Interop Service — Epics

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

INTEROP-EPIC-01 — FHIR R4 Gateway Foundation​

Summary Establish the unified FHIR R4 gateway that proxies resource operations to the correct owning clinical service based on resource type and category. All external FHIR clients interact with a single endpoint regardless of which domain service owns the data.

Description The platform exposes a single FHIR base URL (/fhir/R4/) to external EHR systems, third-party apps, and internal frontends. Today clinical resources are scattered across multiple services with different base paths. This epic builds the stateless routing layer that reads a configurable fhir_routing_rules table and proxies inbound FHIR requests (read, search, create, update) to the correct upstream service while normalising responses into a valid FHIR Bundle or resource.

Acceptance Criteria

  • FHIR routing table covers all 14 resource types owned by platform services
  • CapabilityStatement (GET /fhir/R4/metadata) dynamically generated from routing table and cached in Redis (5 min TTL)
  • Resource-type + category-based routing resolves to the correct owning service
  • JWT authentication enforced on all FHIR endpoints via Keycloak JWKS
  • ABAC check delegated to access-policy-service for patient-linked resource reads
  • Fan-out merge (multi-service search) preserves tenantId isolation
  • Partial fan-out failure returns OperationOutcome with detail; remaining entries still returned
  • All FHIR errors returned as OperationOutcome (not generic JSON)

Priority: Critical Labels: fhir-gateway, routing, platform-foundation Linked FRs: FR-INTEROP-001, FR-INTEROP-002, FR-INTEROP-003, FR-INTEROP-004

INTEROP-EPIC-02 — HL7 v2 Inbound MLLP Engine​

Summary Build the MLLP listener that accepts ADT, ORM, ORU, and VXU messages from external hospital systems, translates them to FHIR R4 resources or platform events, and persists a full audit log with deduplication.

Description Legacy HIS and EMR systems in Afghanistan primarily communicate via HL7 v2 over MLLP. This epic delivers the TCP listener (port 2575, TLS with mutual client certificate authentication), the message parser (MSH/PID/PV1/OBR/OBX/NK1/RXA segment support), and the mapping pipeline that converts each message type into the appropriate FHIR resource or platform event. All inbound messages are stored immutably in hl7_messages for replay and audit. Deduplication uses UNIQUE(connector_id, message_control_id, sending_app) to prevent duplicate downstream processing.

Acceptance Criteria

  • MLLP listener accepts TLS connections with client certificate validation
  • ADT A01/A03/A04/A08/A40 messages → FHIR Patient / Encounter events published to NATS
  • ORM O01 messages → ServiceRequest forwarded to orders-service via FHIR PUT
  • ORU R01 messages → Observation + DiagnosticReport forwarded to laboratory-service
  • VXU V04 messages → Immunization forwarded to immunizations-service
  • ACK (AA/AE/AR) returned within 500ms
  • All raw messages stored with SHA-256 hash; duplicate MSH-10 silently ACK'd without reprocessing
  • Non-parseable messages sent to DLQ; interop_hl7_dead_lettered_total incremented; integration admin alerted

Priority: Critical Labels: hl7v2, mllp, inbound, integration Linked FRs: FR-INTEROP-005, FR-INTEROP-006, FR-INTEROP-007, FR-INTEROP-008

INTEROP-EPIC-03 — HL7 v2 Outbound Delivery​

Summary Deliver platform clinical events as HL7 v2 messages to registered external systems (HIS, reference labs, regional health exchanges) via configured MLLP connectors.

Description Clinical events published to NATS (lab results, radiology reports, immunisation records) must be relayed to external systems that only support HL7 v2. This epic builds the outbound connector framework: subscription to relevant NATS subjects, mapping from FHIR resources to HL7 v2 segments (ORU R01, VXU V04), and delivery via MLLP with retry, circuit-breaker, and dead-lettering. Each connector stores its configuration (host, port, TLS cert, auth_config encrypted with AES-256-GCM) in interop_connectors.

Acceptance Criteria

  • lab.result.released → ORU R01 delivered to registered lab-result destinations
  • immunization.administered → VXU V04 delivered to immunisation registry connectors
  • Connector configuration CRUD via admin API; connector status tracked (active/inactive/error)
  • TLS client cert rotation supported via connector update (no restart required)
  • Exponential back-off (3 attempts, 30s / 5m / 30m intervals) before dead-lettering
  • connector.delivery_failure_rate alert fires when failure rate > 5% over 15 min
  • auth_config field stored encrypted; never returned in API responses

Priority: High Labels: hl7v2, mllp, outbound, connector Linked FRs: FR-INTEROP-009, FR-INTEROP-010, FR-INTEROP-011

INTEROP-EPIC-04 — FHIR Bulk $export and $import​

Summary Implement FHIR $export (system-level and patient-level) and $import for bulk data exchange with the national health data warehouse, regional HIEs, and population analytics pipelines.

Description The Ministry of Public Health requires periodic bulk extracts of de-identified patient data in NDJSON format for national reporting. Partners also need to bulk-load historical records on onboarding. This epic builds the asynchronous export worker (FHIR Bulk Data Access IG compliant), the MinIO streaming writer for NDJSON output, and the import ingestion pipeline. All bulk operations require explicit tenant scoping and AFG-Core profile validation on imported resources.

Acceptance Criteria

  • POST /fhir/R4/$export kicks off background job; 202 Accepted with Content-Location polling URL returned
  • Export status polled at GET /fhir/R4/$export/{jobId}; 200 when complete with NDJSON file links (pre-signed MinIO URLs, 24h TTL)
  • All 14 routed resource types supported for system-level export
  • Patient-level export (/fhir/R4/Patient/{id}/$export) scoped to single patient; ABAC enforced
  • Import: POST /fhir/R4/$import validates each resource against AFG-Core profile before routing to owning service
  • Partial export failures recorded in error manifest; job status set to partial not failed
  • Export files deleted from MinIO after configurable TTL (default 7 days)
  • Bulk export tested for all 14 resource types in integration suite

Priority: High Labels: fhir-bulk, export, import, moph-reporting Linked FRs: FR-INTEROP-012, FR-INTEROP-013

INTEROP-EPIC-05 — AFG-Core Profile Enforcement​

Summary Enforce Afghanistan national FHIR profile (AFG-Core) on all externally sourced resource writes, with configurable validation mode (error vs. warn) and profile version management.

Description The Ministry of Public Health mandates that all clinical data entering the national platform conforms to the AFG-Core FHIR profile (extensions for national IDs, Afghan administrative geography, facility codes). This epic integrates the HAPI FHIR validator in error or warn mode, captures validation failures as structured OperationOutcome entries, and provides an admin API to update the pinned profile version when MoPH releases new conformance packages.

Acceptance Criteria

  • FHIR_PROFILE_VALIDATION_ENABLED=true (default) validates all external writes against AFG-Core StructureDefinitions
  • Validation mode error rejects non-conformant resources with 422 Unprocessable Entity + OperationOutcome
  • Validation mode warn logs failure metric but allows resource through; configurable per connector or globally
  • interop_profile_validation_failures counter labelled by resource type and violation code
  • Profile version stored in interop_connectors.afg_core_version; admin can update without service restart
  • CapabilityStatement lists implementationGuide references for all active AFG-Core versions
  • Integration tests validate ADT, ORM, ORU payloads against current profile package

Priority: High Labels: afg-core, fhir-conformance, moph, clinical-safety Linked FRs: FR-INTEROP-014, FR-INTEROP-015

INTEROP-EPIC-06 — Connector Registry and Management​

Summary Provide a full lifecycle management API for HL7 v2 connectors (inbound listeners and outbound destinations) including secure credential storage, health monitoring, and activation controls.

Description Integration administrators need a governed way to register, configure, and monitor the HL7 v2 connections to external systems without direct database access or service restarts. This epic delivers the connector CRUD API, the port-conflict guard on activation, the health probe that periodically checks MLLP reachability, and the admin dashboard data API.

Acceptance Criteria

  • POST /v1/interop/connectors creates connector with direction (inbound/outbound), host/port, TLS cert, and encrypted auth_config
  • Unique port constraint checked on activation; conflict returns 409 with detail
  • PATCH /v1/interop/connectors/{id}/activate starts the MLLP session; deactivate tears it down gracefully
  • Connector health state (healthy/degraded/unreachable) updated by background prober every 60s
  • GET /v1/interop/connectors/{id}/metrics returns delivery stats (sent, failed, DLQ'd) for last 24h
  • Credentials (auth_config) encrypted at rest (AES-256-GCM); field redacted in GET responses
  • TLS client certificate expiry alert fires 30 days before expiry

Priority: High Labels: connector-registry, admin, mllp Linked FRs: FR-INTEROP-016, FR-INTEROP-017

INTEROP-EPIC-07 — Third-Party EMR Coexistence​

Summary Define and implement the adapter framework for coexistence with existing standalone EMRs during the transition period, ensuring bidirectional data synchronisation and regression safety on EMR upgrades.

Description Several facilities run existing EMR installations (OpenMRS, proprietary systems) that will not be decommissioned immediately. During the coexistence window these systems must send and receive data via the interop-service. This epic formalises the adapter pattern (versioned per partner), the EMR-specific field-mapping configuration, and the regression test suite run on each partner EMR upgrade notification.

Acceptance Criteria

  • Adapter versioning: connector.adapter_version field; breaking changes increment version
  • EMR-specific segment overrides configurable via connector.mapping_overrides (JSON)
  • Regression test suite per registered partner runs in CI; blocks activation if any test fails
  • PATCH /v1/interop/connectors/{id}/mapping-overrides API for integration admin
  • Partner change notification webhook: interop-service can receive a POST /v1/interop/connectors/{id}/upgrade-notice to trigger regression run
  • Documentation of all mapping overrides published to GET /v1/interop/connectors/{id}/mapping-schema

Priority: Medium Labels: emr-coexistence, adapter, migration Linked FRs: FR-INTEROP-018

INTEROP-EPIC-08 — FHIR Terminology Operations Proxy​

Summary Proxy FHIR terminology operations ($lookup, $expand, $validate-code, $translate) from external clients and partner systems to the platform's terminology-service without requiring external clients to know the internal service topology.

Description External FHIR clients expect terminology operations at the FHIR base URL (/fhir/R4/CodeSystem/$lookup, /fhir/R4/ValueSet/$expand, etc.). Rather than duplicating terminology logic in interop-service, these operations are proxied to terminology-service with JWT propagation and caching for common lookups (SNOMED, LOINC, ICD-10-AM).

Acceptance Criteria

  • GET /fhir/R4/CodeSystem/$lookup proxied to terminology-service; response cached with 1h Redis TTL
  • GET /fhir/R4/ValueSet/$expand proxied; count and offset parameters forwarded
  • POST /fhir/R4/CodeSystem/$validate-code proxied; 200/422 result preserved
  • POST /fhir/R4/ConceptMap/$translate proxied; JWT propagated for audit trail
  • Terminology-service unavailability returns 503 OperationOutcome; no caching of errors
  • CapabilityStatement lists all four operations with correct rest.resource.operation entries

Priority: Medium Labels: terminology, fhir-proxy, snomed, loinc Linked FRs: FR-INTEROP-019, FR-INTEROP-020