Interop Service — Application Logic
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Use Cases
Commands
| Use case | Command | Actor |
|---|---|---|
| Register integration connector | RegisterConnectorCommand | Integration admin |
| Activate / deactivate connector | SetConnectorStatusCommand | Integration admin |
| Process inbound HL7 v2 message | ProcessHl7InboundCommand | System (MLLP) |
| Send outbound HL7 v2 message | SendHl7OutboundCommand | System (NATS event) |
| Start bulk FHIR export | StartBulkExportCommand | Authorized external client |
| Import FHIR resources (bulk) | StartBulkImportCommand | Integration admin |
| Update FHIR routing rule | UpdateFhirRoutingRuleCommand | Platform admin |
| Validate FHIR resource against profile | ValidateFhirResourceCommand | Internal / external |
Queries
| Use case | Query | Returns |
|---|---|---|
| FHIR resource read | RouteFhirReadQuery | Proxied response from owning service |
| FHIR resource search | RouteFhirSearchQuery | Proxied / merged results |
| FHIR CapabilityStatement | GetCapabilityStatementQuery | Consolidated CapabilityStatement |
| Bulk export status | GetBulkExportStatusQuery | Job status + file URLs |
| HL7 message log | GetHl7MessageLogQuery | Paginated message history |
| Connector list | GetConnectorsQuery | Active connectors for tenant |
2. Orchestration Flows
2.1 FHIR Request Routing
2.2 HL7 v2 Inbound ADT Processing
2.3 HL7 v2 Outbound ORU (Result Export)
2.4 FHIR Bulk Export
3. Ports
| Port | Direction | Adapter |
|---|---|---|
IMllpServer | Inbound | TCP MLLP listener (node net module with framing) |
IFhirServiceRouter | Outbound | HTTP adapter per owning service; routing table |
IHl7MessageRepository | Outbound | Drizzle ORM → PostgreSQL |
IBulkStoragePort | Outbound | MinIO adapter for NDJSON export files |
IEventPublisher | Outbound | NATS JetStream |
IAbacPort | Outbound | access-policy-service for FHIR boundary ABAC |
IProfileValidatorPort | Outbound | HAPI FHIR validator or internal schema validator |
4. Saga / Outbox Pattern
- HL7 inbound processing uses an outbox worker: message stored first (ACK sent), then processed asynchronously. This ensures idempotent ACK even if downstream services are temporarily unavailable.
- Outbound HL7 messages are queued in
hl7_messages(outbound=true) and sent by the MLLP client worker. Retry onNACKor timeout with exponential backoff. - Bulk export jobs run as background workers; progress tracked in
bulk_export_jobs.
5. Error Handling
| Scenario | Strategy |
|---|---|
| FHIR owning service unreachable | Return FHIR OperationOutcome with transient severity; 503 to client |
| HL7 parse error | Store raw message; mark parse_failed; return AE ACK to sender; alert integration admin |
| ABAC denial on FHIR read | Return OperationOutcome 403 with security issue code |
| Bulk export resource service failure | Partial export recorded; job status partial; client informed |
| MLLP connection timeout | Retry 3 times; mark connector degraded; alert |
| Duplicate HL7 message | Check (connector_id, message_control_id, sending_app); return AA ACK; skip processing |