Concepts

How the EDFlow integration model works: sites, sources, encounters and events, facts and derived stages, projections and minimum necessary data, idempotency, ordering and precedence, and the early-arrival buffer.

The data flow

flowchart LR
  EHR[EHR: Epic, Oracle Health, MEDITECH] -->|HL7 v2, FHIR| ENG[Hospital integration engine]
  ENG -->|events, FHIR, HL7 over HTTPS| ING[Ingest: /v1 or /ehr/v1]
  CON[Staff console] -->|manual events| PIPE
  SIM[Simulator, sandbox only] --> PIPE
  ING --> PIPE[One pipeline: validate, tripwire, idempotency, apply]
  PIPE --> FACTS[(Facts by precedence)]
  FACTS --> STAGE[Derived stage, tasks, care team, results state]
  STAGE --> PROJ[Projections]
  PROJ --> PT[Patient view]
  PROJ --> FAM[Family view]
  PROJ --> STAFF[Staff board]
  PROJ --> API[Integration API and webhooks]

Every ingest path (normalized events, FHIR, HL7 v2, the signed profile, the staff console and the simulator) ends in the same pipeline. Transport and authentication differ; semantics don't.

Sites and sources

A site is one emergency department, addressed by its code (for example kb-main-ed).
A source is one sender, usually one engine channel. It is bound to the sites and event types it may send, and to a versioned mapping profile.
An app (for the REST API) belongs to one organization and one environment, and is bound to up to 50 sites. An app with ingest scopes is linked to one source.

Encounters and events

An encounter is one ED visit, identified by your EHR's visit identifier (Epic CSN, Oracle FIN, MEDITECH account or visit number). EDFlow hashes it on receipt and returns its own opaque id (enc_…).
An event asserts current state: "the patient arrived at 08:02", "the triage was CTAS 3 at 08:15", "this order is in the lab". Events are not deltas.
23 event types cover arrival, triage, location, assessment, disposition, departure, cancellation, patient updates, merges, care team, orders and their status, consults, admission, codes, census, roster and heartbeat. See Events.

Facts, stages and projections

Accepted events update facts, grouped (arrival, triage, location, assessments, disposition, lifecycle, each order, each consult, care-team members).
EDFlow re-derives the stage, tasks, care team and results state from the facts.
Each audience reads through its own projection: patients, family, staff, the waiting-room display and API clients each get an allow-listed view. API clients never receive names, dates of birth, CTAS, chief complaint, free text or result content.

Minimum necessary

Result values, notes, diagnoses, medications, allergies, health card numbers, addresses, phones and emails are prohibited fields: an event containing any of them, at any depth, is rejected before anything is stored.
Family name and date of birth are used only to build a match key for patient sign-in, then discarded.
The FHIR and HL7 adapters drop these elements before mapping.

Idempotency

The key is (source, event id), kept for 30 days.
Same id and same payload: duplicate, nothing changes.
Same id, different payload: idempotency_conflict, unless the mapping profile changed or it's a dead-letter replay, in which case the new payload supersedes through normal precedence.
Ids must be deterministic from source data, so retries and replays produce the same ids, and must never contain patient identifiers.

Ordering and precedence

Events can arrive in any order. For each fact group, the assertion with the greatest precedence wins: record time, then status rank (orders only), then sequence, then receive time.

An older assertion that arrives late never overwrites newer state, but can fill a missing timestamp.
A later-recorded correction wins, even if it "goes backwards" (for example a corrected triage time).
Order status only moves forward unless the event is a correction, a cancellation or an explicit reversal.
Terminal states (departed, cancelled) are reversed only by an explicit event or a staff reopen.
Patient notifications fire once per milestone, on the first transition. Corrections update what's shown without notifying again.

The early-arrival buffer

An event for an encounter or order EDFlow doesn't know yet is buffered for up to 6 hours (at most 500 per encounter) and applied when the parent arrives. After 6 hours it is dead-lettered and you're alerted. Result events that carry the order's code and category create the order, so result feeds never depend on the order feed.

Live and backfill

live (default): state updates and notifications. Live events more than 30 minutes old update state silently.
backfill: for the go-live census sync and outage recovery. State and analytics update; nothing is ever notified.

Feed health and reconciliation

Send system.heartbeat every 60 s per feed. After 5 minutes of silence the feed is delayed, after 15 minutes down.
Send department.roster_reported every 15 minutes. An active encounter missing from two consecutive complete rosters is closed quietly. A roster that would close too many encounters at once is quarantined for review.