Run the clinical ecosystem

This guide stands up the three sibling stacks beyond the domain controller and connects them into one HL7 pipeline. It assumes the DC is already running. Each stack is its own repo under the bingham org; clone them beside samba-domain-controller.

The conceptual picture is on The four-plane architecture; this is the runbook.

1. Create the shared HL7 bus

The MLLP feed and the JDBC write both ride a dedicated bridge network. Create it once:

docker network create hl7-bus

2. Application plane — OpenEMR

cd gh-openemr
cp .env.example .env          # set DB + admin passwords
make up                       # first boot auto-installs (a few minutes)

Served at https://emr.l.supported.systems. The MariaDB joins both its private network and hl7-bus (so the engine can write to it) but is never published to the host.

Authenticate OpenEMR against AD

OpenEMR’s LDAP is bind-as-user: each clinician binds to AD with their own credentials over STARTTLS, so no service account is needed and the password is never stored in the EMR.

make fetch-ca        # pull the DC's CA cert (for STARTTLS) into certs/
make ldap-setup      # set the gbl_ldap_* globals + install the CA cert
make provision-user U=gregory.house F=Gregory L=House   # one clinician
make provision-cast                                     # OR: the whole AD cast (~78)

provision-user adds one clinician; provision-cast reads the transitive members of the AD Clinicians group and provisions them all (idempotent), so any clinician can log in. U must equal the AD sAMAccountName. The login validates against the DC; the local OpenEMR password is an unused random value. The admin account stays on local auth as a break-glass login.

Stop the registration nag

make no-telemetry opts the install out of product registration + anonymous telemetry and suppresses the startup dialog for every user.

3. Activity plane — Simulated Hospital

cd gh-simhospital
cp .env.example .env
make up               # first build compiles from source (a few minutes)

The control dashboard is at https://sim.l.supported.systems/dashboard/. By default it speaks MLLP to the engine (SIM_OUTPUT=mllp, MLLP_DEST=oie:6661); set SIM_OUTPUT=stdout to fall back to logging. Arrival rate is PATHWAYS_PER_HOUR in .env. The deep dive — pathways, the segment mechanism, and the gotchas — is in Simulated Hospital.

4. Integration plane — OpenIntegrationEngine

cd gh-integration
cp .env.example .env          # set keystore + the OpenEMR DB password
make up                       # first boot ~60-90s (initialises Derby)
make provision                # import + deploy the ADT->OpenEMR channel
make stats                    # received / sent / error

The web administrator is at https://integration.l.supported.systems. make provision deploys the channel that maps every HL7 segment into OpenEMR (see the mapping table in the four-plane explanation).

5. Watch it flow

With all three up, patients begin landing in OpenEMR. Burst a batch by raising PATHWAYS_PER_HOUR (e.g. 2500) and make restart in gh-simhospital, then dial back to a trickle (120). Verify:

# in gh-integration
make stats        # received == sent, error 0

# in gh-openemr — counts climbing
docker compose exec -T openemr-mariadb \
  mariadb -uroot -p"$DB_ROOT_PASSWORD" openemr -e \
  "SELECT (SELECT COUNT(*) FROM patient_data) patients,
          (SELECT COUNT(*) FROM lists WHERE type='allergy') allergies,
          (SELECT COUNT(*) FROM procedure_result) labs;"

Then open a patient in OpenEMR and you will see their allergy, diagnosis, surgery, and lab panels — all from the stream.

6. Seed a curated caseload (optional)

For a stable set of recognizable charts in a demo, on top of the live stream:

# in gh-openemr
make seed-demo            # 12 "diagnostic caseload" patients assigned to gregory.house
make seed-immunizations   # add immunizations to that caseload

Why immunizations are seeded, not fed

Vitals, labs, allergies, diagnoses, and procedures arrive on the HL7 feed. Immunizations don’t — Simhospital has no immunization pathway step (no RXA/VXU), so they can’t be generated upstream. make seed-immunizations writes a realistic set (Influenza, Pneumococcal, with CVX codes) directly onto the curated caseload.

Teardown

Each stack has make down (keeps volumes). The DC is unaffected — the clinical ecosystem is layered on top and can be torn down and rebuilt from code independently.