Emulators & the non-PHI version of the system

The EMR emulators were created to test and demonstrate this software. Registering with fifteen vendors takes weeks each, and sandboxes are not always obtainable at all (MEDITECH has no self-service sandbox). The emulators are synthetic stand-ins for every profiled vendor, so the entire integration — auth, bulk export, writes, in-context launch — can be exercised and shown end to end without a real EMR and without a single byte of PHI. The same machinery is how you run a complete non-PHI version of the platform for evaluation, demonstration, training and CI.

1. What they are

One server per vendor (emulators/ in the repository; runbooks/RUNBOOK_EMULATORS.md is the operational reference). All data is synthetic — one set of fake patients, imported from a single source (scripts/mock_epic_server.py) rather than copied, so there is exactly one synthetic dataset in the repository.

2. Usage

Start them all, or one vendor:

python -m emulators                    # all fifteen (ports 9101–9115)
python -m emulators --vendor cerner    # one vendor

Point the platform at an emulator exactly as at a real EMR — that is the point. Set the FHIR base URL to the emulator (http://127.0.0.1:9101/api/FHIR/R4 for Epic), select the vendor profile, and run the bulk import: kickoff, a genuinely asynchronous status poll (the first poll returns 202, as every real implementation does), NDJSON download, encrypt-store-index. Plain http is accepted only for loopback (127.0.0.1, ::1, localhost) — the same carve-out RFC 8252 makes — and a remote http issuer is refused outright.

In-context launch, end to end: open http://127.0.0.1:9101/emulator/launch — a stand-in for a clinician viewing a chart — and it sends a SMART EHR launch at the platform (python -m emulators --record-url http://127.0.0.1:8080/smart/launch). The launch is honest: the id_token is really RSA-signed with a key published at /.well-known/jwks.json, PKCE is enforced, and authorization codes are single-use — an emulator handing out unsigned tokens would let a client that skips signature verification pass its tests, which is precisely the defect worth catching. Register an emulator in the SMART issuer allowlist like any EMR, and mark it record_source: true if the deployment ingests from it (the loader matches that key literally; a misspelling is silently forward-compatible, so confirm by launching, not by re-reading the YAML).

3. They reproduce the seams, not just the happy path

Testing against one generic FHIR server proves very little — integrations break on the vendor seams, and each emulator reproduces its vendor's honestly, including the unhelpful behaviors:

• athenahealth rejects a JWT assertion with invalid_client, as it would live; a client secret sent to any JWT-only vendor gets the mirror-image refusal.
• Cerner demands explicit system scopes at the token endpoint — a scope-less request (Epic's normal shape) or a wildcard gets invalid_scope, exactly as Oracle Health documents — and it also accepts the Basic-header secret mode.
• NextGen refuses $export with an OperationOutcome, not an empty result — "unsupported" must never be mistakable for "no data".
• Epic advertises create for almost nothing; MEDITECH and eClinicalWorks for nothing at all — so the delivery capability check has something real to refuse.
• Only Cerner honors If-None-Exist; the others return 412, which is what makes duplicate-prevention testable.
• Pagination is two per page regardless of _count, so a mishandled next link fails here, not against a large practice.

4. What a green run proves — and does not

It proves the client handles the shapes these servers produce: the auth flows, pagination, the async bulk-export handshake, capability-gated writes, conditional create, and in-context launch with a verified id_token — the majority of integration defects. It is not certification. A particular health system's build may behave differently; every vendor profile still requires confirmation against the instance's own CapabilityStatement, and the emulators never override that.

5. Setting up the non-PHI version of the system

A complete deployment of the real software in which no real person's data exists anywhere — the configuration for evaluation, demonstrations, training and CI, and the configuration this platform's own development runs on:

1. Deploy the platform normally — the full stack from Setup & deployment (dev tfvars are fine), or a local scripts/run_web_dev.sh instance. Nothing about the non-PHI configuration is a different codebase.
2. Generate the synthetic population: scripts/generate_corpus.py builds a Synthea-generated corpus — invented people with clinically plausible longitudinal records. Synthea is directionally, not quantitatively, calibrated: it supplies volume and structure, never an epidemiological claim.
3. Load it through the real pipeline — either directly (scripts/load_local_corpus.py, which runs reference normalization, sensitivity classification, encrypt-store-index) or the full dress rehearsal: serve the corpus from the Epic emulator and run the bulk import manager against it, so kickoff → poll → NDJSON → store is exercised end to end.
4. Use development personas (PHI_AI_WEB_DEV_PERSONAS) for the role-switching walkthrough — fabricated identity, every action still audited against the persona shown, and never enabled in production.
5. Enable the assistant against the synthetic corpus — the full RAG loop, citations, withholding and refusals all demonstrate with zero PHI exposure.
6. Exercise every seam: the emulators for all fifteen vendors, the streaming and export managers' seeded specimens, the consent gate, the Part 2 refusal, the audit chain verification.
7. Say what it is. A non-PHI deployment should label itself synthetic on every page — a fixed banner stating no real patients exist in it — because the honest label is what lets you show the system to anyone without a BAA in sight.

What the non-PHI version gives you: every feature of the platform — the gates, the assistant, the integration managers, the audit trail — behaving exactly as production does, demonstrable to any audience, testable in CI, with no real patient in the blast radius of a mistake.

6. This demonstration site's synthetic environment

Everything below is demonstration data — it documents this public site's synthetic environment, and none of it is a property of the platform. The system documentation deliberately describes the system without it.

6.1 The demonstration cast

The header's persona switcher signs you in as one of six synthetic profiles. Every one is fictional; the System Administrator carries the author's name by design.

6.2 The synthetic dataset

• 33,311 synthetic patients with longitudinal records — conditions, medications, allergies, encounters, labs and vitals, documents, immunizations, procedures, claims with line items. A generated national population: a realistic age pyramid, multicultural names, age-appropriate payer mix, and prevalence- weighted conditions across all fifty states. Deterministic generator (scripts/gen_population.py); no real person's data appears anywhere on this site.
• Psychotherapy notes are hand-authored synthetic specimens, including 42 CFR Part 2 examples, so the segregation and redisclosure refusals can be demonstrated on real content shapes.
• Imaging is generated on this server — deterministic synthetic phantom frames per study, watermarked SYNTHETIC, across CT, radiographs, ultrasound and retinal modalities. Some studies carry a planted finding for the AI read to discover.
• Ambient encounters are two scripted, synthesized recordings — a Texas in-person diabetes follow-up for Rolf Marlin Grant and a California telehealth hypertension check for Rafaela Yolando Satterfield — transcribed by the self-hosted listener; the transcripts shown are its genuine output.
• The source EMR on the integration screens is a ten-patient synthetic roster that exists "at the vendor" until you import it — the day-one reality of a new patient between bulk runs.

6.3 The demonstration model and limits

• Claude Sonnet 5 is the demonstration model only. In a deployment you bring your own model under your own BAA with your AI provider; every AI feature degrades to an honest scripted responder when live calls are off.
• Per-visitor rate limits keep the public demo affordable: 20 assistant questions/hour, 15 documentation-assistant questions/hour, 8 fresh AI imaging reads/hour (studies already read stay available to everyone).
• No live microphone, ever. The ambient capture controls drive the bundled recordings; a public site must not collect real voices.

6.4 A worked example against this dataset

The API documentation uses placeholder values; against this site's seeded data, the same retrieval tool call looks like this:

{"name": "search_patients", "input": {"query": "rolf grant"}}
→ [{"id": 951, "mrn": "MRN-106857", "name": "Rolf Marlin Grant",
    "birth_date": "1935-05-13", "gender": "male", "payer": "Humana"}]

Citations in assistant answers use the same synthetic identifiers, e.g. [MRN-106857 · chart].

Companions: Setup & deployment for the production path, and EMR connections for the vendor seams the emulators reproduce.