Architecture overview

JamBridge is a Spring Boot 3.3 application built on Apache Camel 4. It runs as a single JVM process with multiple MLLP consumers and an HTTPS admin API.

System diagram

                         ┌──────────────────────────────────────────┐
 Hospital HIS            │              JamBridge :8443              │
 (Epic/Cerner/           │                                           │
  MEDITECH)              │  MLLP Consumers                           │
     │                   │  ┌─────────────────────────────────────┐  │
     ├── ADT :2575 ──────►  │ :2575 ADT  :2576 ORU  :2577 ORM    │  │
     ├── ORU :2576 ──────►  │ :2578 MDM  :2579 QBP  :2580 RDE    │  │
     ├── RDE :2580 ──────►  │ :2581 SIU  :2582 MFN               │  │
     │                   │  └─────────────┬───────────────────────┘  │
     │                   │                │                           │
     │                   │  Camel Route Pipeline                      │
     │                   │  ┌─────────────▼─────────────────────┐    │
     │                   │  │ 1. RECEIVE   — parse + dedup       │    │
     │                   │  │ 2. ENRICH    — MPI + facility reg  │    │
     │                   │  │ 3. TRANSFORM — HL7v2 → FHIR R4    │    │
     │                   │  │ 4. GOVERN    — consent check       │    │
     │                   │  │ 5. PERSIST   — HAPI FHIR write     │    │
     │                   │  │ 6. DISPATCH  — subscriptions       │    │
     │                   │  │ 7. ACK       — MSA|AA + ATNA       │    │
     │                   │  └─────────────────────────────────────┘   │
     │                   └──────────────────────────────────────────┘
     │
     │                    External services
     │                   ┌────────────────────────────────┐
     │                   │ JamMPI  :8081  Patient $match   │
     │                   │ JamFR   :8089  Facility registry│
     │                   │ JamTS   :8085  Terminology      │
     │                   │ JamConnect :8091  Consent + CDS │
     │                   │ HAPI FHIR :8080  FHIR R4 store  │
     │                   │ JamGuard :8094  Safety rules    │
     │                   └────────────────────────────────┘
     │
     └── MSA|AA ◄─────────────── JamBridge

Key classes

Class	Package	Role
BridgeCamelRoutes	routing	Defines all 8 Camel MLLP consumer routes
Hl7v2Parser	parser	HAPI HL7v2 Terser — parses MSH, PID, PV1, OBX
MessageIdempotencyFilter	dedup	MSH-10 deduplication against hie_transaction_log
FacilityCodeResolver	enrich	JamFR ITI-90 lookup with 5-min cache
MpiClientService	enrich	JamMPI Patient/$match (ITI-119)
Hl7v2ToFhirMapper	transform	PID→Patient, PV1→Encounter, OBX→Observation
JamConnectClient	govern	Consent check + POST_WRITE dispatch
FhirClientService	persist	HAPI conditional create/update + circuit breaker
SubscriptionEventDispatcher	dispatch	FHIR subscription fan-out
AtnaService	audit	RFC 5425 TLS syslog + BALP AuditEvent
Hl7v2AckBuilder	ack	MSA

Transaction lifecycle

Every message gets a UUID transaction ID at reception:

BR01-26060612-001
└── Prefix: facility code
        └── Date: YYYYMMDD
                └── Sequence: 3-digit counter

The transaction is written to hie_transaction_log with:

• status: RECEIVED → PROCESSING → SUCCESS | CONSENT_NACK | ERROR
• duration_ms: wall-clock time for the full pipeline
• golden_patient_id: the MPI golden record linked to this message
• fhir_resource_id: the HAPI FHIR resource ID written