Integration Engine for Modern Healthcare Solutions

Interbox

Orchestrate healthcare data with a durable, queue-driven runtime. Interbox streamlines HL7v2 modernization and custom workflows, delivering FHIR to Aidbox.

Book a Demo

Solutions born from years of integration experience

Our deep experience with HL7v2, C-CDA, and X12 across major EHRs taught us where production pipelines break. Interbox builds those lessons into every feature.

Efficient FHIR delivery

Hash-based diffing deduplicates bundles and picks optimal write strategy per resource. Parallel writes scale throughput — Aidbox load stays minimal, partial updates keep data consistent.

Tailored pipelines

Design workflows for your unique integration requirements. Leverage our built-in library or extend the pipeline with custom TypeScript logic at any stage.

Terminology mapping

Map local lab codes, patient classes, and status values to LOINC, SNOMED, and FHIR ValueSets without leaving the workflow.

Operational visibility

A robust model of workers and persistent queues provides full visibility. Audit or troubleshoot pipeline state at any step via our dedicated persistence layer.

Developer workspace

Your Git repo plugs directly into Interbox for an instant, hot-reloading development loop. Use our TypeScript SDK and AI assistance to build workers and pipelines — you focus on the logic, and we handle the rest.

Nothing is ever dropped

Every error, message, and result stays in the queue until you resolve it. Retry or fix on your schedule — not under pressure.

The runtime that runs your mappings

Workers chain through typed PostgreSQL-backed queues. Each stage is a built-in from the SDK or a worker you wrote in your repo. Every failure splits onto the pipeline's errors queue — nothing is dropped.

Runner

hl7-to-aidbox

live · 5 workers

Senders · HL7v2 over MLLP

Epic Cerner Meditech

mllpSource

@interbox-sdk

TCP/MLLP listener — emits raw HL7v2 messages.

hl7 : queue<string>

parser

@interbox-sdk

HL7v2 → typed ParsedMessage with $N_field indexing.

parsed : queue<ParsedMessage>

hl7FhirMap

your mappings

Your mappings drive this stage — HL7v2 → FHIR resources.

fhir : queue<Resource[]>

fhirBundler

@interbox-sdk

Groups converted resources into a transaction Bundle per message.

bundle : queue<Bundle>

fhirDestination

@interbox-sdk

Hash-based PUT vs PATCH vs skip — dedupes unchanged resources; partial updates never null fields.

Destination

Aidbox

Patient Encounter Observation …

side channel

__errors.<pipeline>

Every worker auto-emits failed items here as PipelineErrorEvent — payload, reason, worker, timestamp.

At-least-once delivery
Triage & retry from Operations UI
Drain to your own DLQ worker

High-load built-in ingestion worker

Built to solve three production-grade problems that decide whether your integration scales.

Problem

Interbox ingestion worker

Naive approach

Throughput at scale

Heavy multi-threaded ingestion tested on real production pipelines with millions of messages.

Single-threaded ingestion that buckles under realistic message volume.

Data loss

Hash-based checks decide PUT vs PATCH vs skip — partial updates never clobber fields with nulls.

Blind PUT requests overwrite existing fields with nulls and lose data on every retry.

Aidbox extra load

Delivery step hashes each resource and skips writes when content is unchanged. Common reuse cases (Organizations, Practitioners, Coverages) never hit the wire — Aidbox handles only real changes.

Every message rewrites Organizations, Practitioners, and Coverages even when nothing changed. Write volume scales with traffic, not with actual change.

Operations UI for the people running it

Day-to-day work doesn't need a terminal. Operators and integration analysts watch traffic, fix mapping gaps, and replay failures from a UI built for them.

See every message

Live inbox of incoming and outgoing messages. Filter by sender, message type, or status; open one to see the raw HL7v2 next to the resulting FHIR resources.

Resolve mapping gaps without code

When a new local code shows up, your team maps it to LOINC or SNOMED right in the UI. Affected messages reprocess automatically.

Retry after the fix

Failed messages stay safely parked. Fix the root cause, hit retry — no data loss, no manual replays from logs.

Full audit trail

Every status change, retry, and mapping resolution is timestamped and attributed. Compliance and oncall both stay happy.

Your repo is the deployment unit

A Git repo with pipeline.ts, workers/, and mappings/ plugs into the runtime. Push to main; the runtime pulls and reloads — no image rebuilds for mapping changes.

your-org/hl7-pipeline · main

your-org/hl7-pipeline
├── pipeline.ts             # topology: queues + workers
├── workers/
│   ├── normalize-pid.ts    # sender-specific quirks
│   └── persist-audit.ts    # custom DLQ store
├── mappings/
│   ├── pid-patient.ts
│   ├── pv1-encounter.ts
│   └── obx-observation.ts
├── tests/
└── package.json            # "@healthsamurai/interbox-sdk"

Hot-reload from your branch

Push to main — the runtime pulls and reloads. No image rebuilds, no rollout choreography for mapping changes.

Code review, tests, version control

Mappings and pipeline topology live in TypeScript next to your unit tests. PRs, blame, rollbacks — the same workflow as the rest of your stack.

AI assistance, built in

Repo ships with AGENTS.md and HL7v2 spec tooling — Claude Code, Cursor, and Copilot generate segment converters and tests against your structure, with the spec one tool-call away.

pipeline.ts

// pipeline.ts
import { pipeline } from '@healthsamurai/interbox-core';
import {
  mllpSource, parser, hl7FhirMap, fhirBundler, fhirDestination,
} from '@healthsamurai/interbox-sdk';

const p = pipeline('hl7-to-aidbox');

const hl7    = p.queue<string>('hl7');
const parsed = p.queue<parser.ParsedMessage>('parsed');
const fhir   = p.queue<Resource[]>('fhir');
const bundle = p.queue<Bundle>('bundle');

p.add(mllpSource.worker,     'mllp',    { config: { port: 5555 }, out: { messages: hl7 } });
p.add(parser.worker,         'parse',   { config: {}, in: { hl7 },    out: { parsed } });
p.add(hl7FhirMap.worker,     'map',     { config: {}, in: { parsed }, out: { fhir } });
p.add(fhirBundler.worker,    'bundle',  { config: {}, in: { fhir },   out: { bundle } });
p.add(fhirDestination.worker,'aidbox',  { config: { basicAuth }, in: { bundle } });

export default p;

Pipeline as code

Topology is one TypeScript file — queues in, workers in, types enforced

Typed queues. p.queue<T>() binds wire format to compile-time types — producer/consumer mismatches fail to build.
Drop-in workers. Import a built-in or your own from workers/, wire it with p.add().
Errors are first-class. Every pipeline owns __errors.<name> — failed items split off, never lost.
PostgreSQL-backed queues. Persistent durability baked into the runtime.

Mappings as code

HL7v2 → FHIR conversion lives in TypeScript — not in a black box

Field-by-field indexing. Reference HL7v2 fields with the typed $N_fieldName pattern.
IDE autocomplete at every nesting level — segments, fields, components.
Unit and integration tests for every message type.
Code review and version control for every mapping change.

aidbox-hl7v2-example Public reference repo demonstrating the mappings-as-code approach end-to-end.

mappings/pid-patient.ts

// mappings/pid-patient.ts
export function convertPIDToPatient(pid: PID): Patient {
  const patient: Patient = { resourceType: "Patient" };

  patient.identifier = pid.$3_identifier
    ?.map(convertCXToIdentifier).filter(Boolean);

  patient.name = pid.$5_name
    ?.map(convertXPNToHumanName).filter(Boolean);

  if (pid.$7_birthDate) {
    patient.birthDate = convertDTMToDate(pid.$7_birthDate);
  }

  if (pid.$8_gender) {
    patient.gender = GENDER_MAP[pid.$8_gender.toUpperCase()];
  }

  return patient;
}

Two ways we take this to production with you

License & Software

Run Interbox in your stack

Start from the open-source aidbox-hl7v2-example, wrap your mappings into a worker, drop the pipeline into Interbox. Your team owns the repo; Interbox runs it.

Talk to us

Engagement & Team

Bootstrap project

Our engineers work alongside yours — converters for your message types, EHR wiring, operations handoff. You ship faster; your team owns it after.

Get in touch

Questions about Interbox?

Tell us about your HL7v2 senders and your FHIR destination — we'll come back with a concrete shape for the work.

Address: Health Samurai Inc. 1891 N Gaffey St Ste O, San Pedro, CA 90731
Telephone: +1 (818) 731-1279
Email: hello@health-samurai.io