Architecture
How FireSonic receives, persists, processes, validates, and delivers HL7 v2 messages as FHIR R4.
FireSonic uses a durable asynchronous processing model designed for reliability, recoverability, and extensibility. Incoming HL7 v2 messages are persisted before processing, then move through independent transformation, customization, validation, and delivery stages.
Architecture goals
Internal processing pipeline
persist first · process asynchronouslyDurable persistence and internal queues decouple message intake from transformation and downstream delivery.
Main components
| Component | Responsibility |
|---|---|
| MLLP Listener | Accept HL7 v2 over TCP, validate framing, return ACK/NACK, and collect connection metrics. |
| Embedded persistence | Store messages durably, track processing state and history, and support retries and restart recovery. |
| Intake queue | Buffer persisted messages and decouple receive operations from downstream processing. |
| Processing workers | Coordinate scripts, transformation, semantic validation, and delivery. |
| Groovy hooks | Execute organization-specific filtering, normalization, enrichment, reconciliation, and workflow logic. |
| HL7 → FHIR mapper | Perform deterministic Java-based transformation for supported HL7 workflows and FHIR resources. |
| Bundle generation | Assemble generated resources into FHIR R4 transaction Bundles with resource links and idempotent delivery patterns. |
| Semantic validation | Evaluate business, interoperability, and clinical-context rules before delivery. |
| FHIR delivery | Deliver transaction Bundles to the configured FHIR endpoint with timeout, authentication, and retry handling. |
Platform core and customer customization
FireSonic separates generic interoperability behavior from organization-specific workflow logic. This keeps the core mapper stable while allowing each deployment to adapt to local HL7 conventions, terminology, and business rules.
- HL7 v2 parsing and framing
- HL7 → FHIR R4 mapping
- FHIR Bundle construction
- Persistence, queueing, recovery, and delivery
- Filtering and routing decisions
- HL7 normalization before mapping
- FHIR enrichment after mapping
- Terminology reconciliation and local validation
Asynchronous processing and persistence
Incoming messages are persisted locally before transformation starts. Persisted messages survive FireSonic restarts and can re-enter processing or retry workflows without requiring the source system to resend the original HL7 payload.
FireSonic uses SQLite as the default embedded persistence layer to keep single-node deployments lightweight and operationally simple. The database is optimized for local SSD-backed storage and durable queue semantics. See Persistence & Retention for storage, retention, backup, and database-maintenance details.
Failure isolation and recovery
The processing stages are separated so a downstream FHIR outage or a processing failure does not prevent FireSonic from continuing to accept and persist new HL7 messages. Failed or interrupted messages remain traceable by status and can be recovered or retried according to their failure type.
See Reliability & Recovery for message states, retry behavior, circuit breakers, stale-processing recovery, and administrative retry operations.
Workers and concurrency Commercial
Message intake and processing are asynchronous. Commercial editions allow intake and processing worker counts to be tuned for the deployment so FireSonic can better utilize available CPU resources and increase parallel processing capacity.
Runtime extensibility
Groovy scripts and semantic validation rules provide the runtime extension points for customer-specific behavior. Scripts execute at defined lifecycle stages; semantic rules run against the generated FHIR Bundle before delivery.
Automatic hot reload Commercial
Commercial editions can detect script and semantic-rule changes, compile and validate a new generation, and activate it without restarting the FireSonic runtime. Invalid generations do not replace the currently active configuration.