Interop Service — Domain Model

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

1. Aggregates

Represents a configured integration channel to an external system (HL7 v2 feed, FHIR partner, EMR coexistence).

Invariant	Rule
One active connector per (tenant, facility, protocol, direction)	Prevents duplicate listeners on same MLLP port
Auth config encrypted	Credentials never stored in plaintext
Deactivation preserves message log	Disabling connector does not delete historical messages

State machine:

An immutable record of a received or sent HL7 v2 message. Append-only.

Invariant	Rule
Raw payload stored immutably	Raw HL7 bytes never modified after storage
Deduplication	`(connector_id, message_control_id, sending_app)` must be unique
Processing status tracked	`pending → processing → processed → failed → dead_lettered`

Defines how a FHIR resource type is routed to its owning service.

Invariant	Rule
One primary owner per resource type + category	No ambiguous routing without explicit fan-out rule
Fan-out rules for split ownership	`Observation` routes by category (vital-signs vs laboratory)

Tracks a FHIR bulk $export request lifecycle.

Invariant	Rule
One active export per (tenant, group) at a time	Prevents runaway parallel exports
Output files immutable after completion	Signed URLs expire; new export required for refresh

State machine:

Entity	Key attributes	Aggregate
`Hl7ProcessingAttempt`	`id`, `messageId`, `attemptAt`, `status`, `errorDetail`	Hl7Message
`Hl7ResourceLink`	`id`, `messageId`, `resourceType`, `resourceId`, `action`	Hl7Message
`BulkExportFile`	`id`, `jobId`, `resourceType`, `fileUrl`, `count`	BulkExportJob

Value Object	Fields	Rules
`FhirVersion`	enum `R4 \| R4B`	R4 is the baseline
`Hl7MessageType`	`messageCode`, `eventCode` (e.g., `ADT^A01`)	Determines mapper
`ConnectorProtocol`	enum `mllp \| fhir-rest \| sftp \| api-polling`	Drives adapter selection
`ConnectorDirection`	enum `inbound \| outbound \| bidirectional`
`ResourceOwnership`	`resourceType`, `category?`, `serviceUrl`	Routing table entry

Event	Trigger	Key payload
`Hl7MessageReceived`	MLLP message ingested	`messageId`, `connectorId`, `messageType`, `tenantId`
`Hl7MessageProcessed`	Mapping completed + FHIR resource created	`messageId`, `resourceType`, `resourceId`, `tenantId`
`Hl7MessageFailed`	Processing error	`messageId`, `errorCode`, `tenantId`
`Hl7MessageDeadLettered`	Max retries exceeded	`messageId`, `tenantId`
`FhirRequestRouted`	FHIR request forwarded to owning service	`resourceType`, `operation`, `tenantId`
`BulkExportStarted`	$export job started	`jobId`, `groupId`, `tenantId`
`BulkExportCompleted`	$export job completed	`jobId`, `fileCount`, `tenantId`
`ConnectorActivated`	Connector enabled	`connectorId`, `protocol`, `tenantId`
`ConnectorDeactivated`	Connector disabled	`connectorId`, `tenantId`

Term	Definition
Connector	A configured integration channel to/from an external system
MLLP	Minimum Lower Layer Protocol — TCP transport for HL7 v2
Message control ID	Unique identifier assigned by the sending system to an HL7 v2 message
CapabilityStatement	FHIR resource declaring what interactions/resources/profiles the server supports
OperationOutcome	FHIR resource used to return errors and warnings
Fan-out	Routing a single FHIR request to multiple owning services and merging results
Bulk export	FHIR `$export` operation producing NDJSON files of all resources for a group/patient
AFG-Core	Afghanistan national FHIR Implementation Guide extensions and profiles
US Core 6.1	US Core FHIR Implementation Guide version 6.1 (baseline profile set)
IPS	International Patient Summary — FHIR profile for cross-border patient data exchange
VXU	HL7 v2 Vaccination Record Update message type
ORM	HL7 v2 Order Message
ORU	HL7 v2 Observation Result Unsolicited
ADT	HL7 v2 Admit/Discharge/Transfer