On this page — 8 sections
System architecture
The complete architectural reference, diagram-first: the logical layer model, the feature map from every AI feature to its registry slot and model, the end-to-end animated architecture with its component reference, trust boundaries, cloud architecture and failure modes, and the data-flow journeys walked step by step. Every diagram is plain-English on hover; every moving dot is data traveling.
1. Logical architecture — the layers
Six layers, strictly ordered: a request enters at the experience layer and touches data only after governance says yes; the AI core sits beside governance, never above it; and the audit layer underlies everything — including the refusals. No layer is reachable except through the one above it.
Screens act for a signed-in role; every read or write passes the governance layer's gates; the AI core reaches records through those same gates via its role-scoped tools; the data layer is encrypted and sensitivity-fenced; integration is the only door in or out of the deployment; and the audit chain records every crossing.
2. Feature map — features, capability slots, models
Every AI feature resolves through the model registry: the feature names a capability slot, the registry says which enabled model serves that slot, and the monitoring page watches every slot with live metrics and drift recognition. An unregistered model does not execute; a disabled slot degrades its feature honestly. Features that produce documentation converge on one place — the signature queue — because nothing enters a record unsigned.
Ten AI features, one registry. The registry resolves each capability slot to a model — the foundation model you bring, the self-hosted listener, or a built-in — and every inference lands on the audit trail as model.inference. Drafting features converge on the signature queue.
Full architecture with data flows
The whole platform on one page — an AI-native architecture, designed from first principles for AI use of protected data: the animated map first, then a component-by-component reference, the trust boundaries, the deployable platform's cloud architecture, and the failure-mode table. Watch the dots: each moving dot is data traveling — green flows are records arriving, navy flows are people and the AI reading under the platform's rules, orange flows are records leaving, and every faint gray thread reports to the audit trail. Hover over any box for a plain-English explanation.
Records flow from the source EMRs through ingestion into the encrypted Data Store, where sensitive categories are fenced off. People and the AI assistant read through role gates; drafts return to the EMR only with a human signature; exports pass consent gates before anything leaves. Every box reports to the audit trail at the bottom — including the gates' refusals.
1. How to read the picture
- Nothing skips the gates. There is no path from the Data Store to a person, the AI, or another organization that does not pass a role, consent or signature gate. If you trace any navy or orange arrow backward from its destination, you pass through a gate before you reach the data.
- The AI is inside the walls. PHI RAG reaches the Data Store only through the same audited, role-scoped tools people use — the model never holds a database connection, and the foundation model (the LLM you bring — Claude Sonnet 5 in this demo) receives only the excerpts the gates released for the current question.
- The audit trail sees everything. Every arrow that moves data — and every arrow a gate refuses — lands on the hash chain. The trail records references, never content.
- Green in, orange out. Arrival and departure are different disciplines: arrival is about completeness (watermarks, checkpoints, surfaced gaps), departure is about permission (consent gates, exclusion counts, refusals).
2. Component reference
2.1 Source EMRs
- Role: data planes into the AI-native platform — Epic, Oracle Health, athenahealth, eClinicalWorks, MEDITECH, NextGen. Records arrive from them; signed documentation delivers back to them (the chart of legal record, as the law requires — the intelligence, governance and AI-ready data model live in this platform).
- Inputs: signed write-back and configured deliveries.
- Outputs: bulk extracts and streaming events.
- Failure mode: vendor unavailability stalls ingestion — runs fail visibly, watermarks hold, and nothing downstream silently ages.
2.2 Bulk import
- Role: population-scale arrival over the FHIR Bulk Data API.
- Honors: each vendor's real seams — Epic's one-run-per-24h group export with no incremental mode, NextGen's absence of bulk entirely.
- Emits: bulk.completed / bulk.refused.
- Key property: the watermark — the timestamp of the last known-complete extract — advances only on a clean run, so a half-arrived population can never masquerade as the current state.
2.3 Streaming intake
- Role: real-time arrival — ADT admissions and discharges, ORU lab results, X12 835 remittance — on partitioned feeds.
- Key property: per-partition acknowledged checkpoints; a gap between checkpoint and latest offset is displayed with its exact range on the Streaming data screen.
- Deliberate non-feature: gap interpolation. A pipeline that guesses what it missed is a data-integrity incident that has not been discovered yet.
2.4 Encrypt · store · index
Role: the only doorway into the Data Store. Every record — bulk or streamed — is (1) encrypted, (2) classified for sensitivity (sud_part2, mental_health, reproductive, hiv, genetic, or none; psychotherapy content routed to its separate store), (3) normalized (reference resolution, terminology mapping), and (4) indexed for retrieval. Key property: classification happens at the door, not at read time — a record's sensitivity is a stored fact, uniform for every downstream gate.
2.5 The Data Store
- Role: the encrypted holdings — clinical, financial and behavioral-health record classes (the full inventory with live counts is on the Data Store screen).
- Key properties: no direct read path exists; every consumer goes through the gates; the psychotherapy store is physically separate; six integrity checks run live on the Data Store screen, including full audit-chain verification.
2.6 Role · consent · purpose gates
- Role: the enforcement point every read crosses. Evaluates: the profile's permissions (enumerated, no wildcards except the System Administrator's audited *), the record's sensitivity class against the reader's role and the applicable consent, and the session's purpose of use.
- Outputs: released records, plus a withholding count for whatever was held back.
- Emits: phi.disclosure-family events on release, access.denied on refusal. Key property: the gate cannot be bypassed by the AI — the assistant's tools call the same gate code the screens do.
2.7 PHI RAG (retrieval-tuned LLM)
- Role: the assistant. Plans retrieval, calls role-scoped tools, assembles gate-released excerpts, and produces cited answers.
- Contract: answer only from retrieved records; cite as [MRN-xxx · chart]; never assert absence from unretrieved documents; confirm before population sweeps; state withholdings; counts, never lists, on the population plane.
- Controls: the Control panel's retrieval switch (off = the assistant refuses to read the Data Store at all and says so).
- Emits: ai.query per question, plus the tools' own events.
2.8 The foundation model — yours
- Role: the foundation language model PHI RAG runs on, called over the model API at temperature 0 with bounded output.
- Bring your own: this demonstration runs Claude Sonnet 5, but the slot is provider-pluggable — a deployment activates the LLM the organization chooses, under its own BAA with its AI provider.
- Receives: the system contract, the last six turns, the role's tool schemas, and gate-released excerpts — never a database connection, never bulk data.
- Controls: the live-calls switch; off degrades to the scripted fallback.
- Data terms: excerpts are used to answer the question, not to train models, under the organization's agreement with the provider.
2.9 People & screens
- Role: six profiles across the role model, each seeing exactly the screens its permissions allow (the full matrix is in the system documentation).
- Key property: screens check permissions, not roles — role composition changes without touching screens.
2.10 Human signature
- Role: the signature rule's enforcement point. AI drafts queue; a licensed reviewer edits and signs; only the signed artifact acquires a write path to the EMR.
- Emits: signature.committed. Deliberate non-feature: auto-commit, batch signing, or timeout-advance. A draft's only exits are a signature or a return.
2.11 Export managers
- Role: the only doorways out — bulk delivery and outbound feeds. Apply the consent & redisclosure gate, record exclusion counts, honor the destination's write surface, and track acknowledgment.
- Emits: export.completed / export.refused.
- Key property: the three outcomes (complete / failed / refused) are all first-class and all visible in run history.
2.12 The audit trail
Role: the append-only, hash-chained memory of everything above. Every component writes to it; nothing edits it; the Control panel re-derives the full chain on every load and reports intact or the first broken row. In the deployable platform, concurrent writers may fork the chain legitimately; verification understands forks and distinguishes them from tampering.
3. Trust boundaries
Five boundaries, and what is allowed to cross each:
| Boundary | Crosses it | Never crosses it |
|---|---|---|
| Vendor EMR ↔ platform | Authenticated bulk extracts, streaming events, signed write-back, configured deliveries | Unsigned generated content; credentials in either direction beyond the OAuth flows |
| Ingestion ↔ Data Store | Encrypted, classified, indexed records | Unclassified records; unencrypted records |
| Data Store ↔ readers (people or AI) | Gate-released records with withholding counts | Direct queries; sensitive records for excluded roles; psychotherapy content for anyone but the Psychotherapy role |
| Platform ↔ model provider | The contract, the question, gate-released excerpts for this question | Bulk data; a database connection; credentials; records the gate withheld |
| Platform ↔ external recipients | Consent-gated packages with recorded exclusions; acknowledged feed events | Psychotherapy notes (ever); Part 2 content without Part 2 consent; partial exports presented as complete |
4. The deployable platform's cloud architecture
The platform ships this architecture hardened:
- Envelope encryption. Every stored object is encrypted with its own data key; data keys are wrapped by a KMS master key that never leaves the key service. Compromising storage yields ciphertext; key use is itself logged.
- Isolated stores. Record objects, audit events, and psychotherapy content live in separate stores with separate access policies — the psychotherapy separation is infrastructure, not a WHERE clause.
- Relational index + OMOP. A relational index serves the screens; an OMOP common-data-model layer serves research-grade analytics on the de-identified plane.
- IAM enforcement in depth. Roles are enforced in the application and as cloud IAM policy, with the purpose of use carried as an IAM session tag — the storage layer itself can refuse a read whose purpose tag is absent.
- A no-script web tier. The product interface runs under a Content-Security-Policy of script-src 'none': the screens execute no JavaScript, eliminating the XSS class outright. (This documentation's animated diagrams are the one scripted surface, and they render no PHI.)
- Credential hygiene. Model-provider and vendor credentials live server-side in restricted stores, never in pages, never in the repository.
5. Failure modes
What breaks, what happens, and what is designed to never happen:
| Failure | What happens | What never happens |
|---|---|---|
| Bulk download interrupted | Run marked failed; watermark holds; retry is a fresh run | A partial population presented as current |
| Stream broker restart | Gap surfaced with exact offsets; processing resumes from checkpoint | Interpolated events; silently skipped offsets |
| Model API down | Error stated; scripted fallback answers, labeled; questions still audited | Unlabeled degraded answers; lost audit events |
| Export destination rejecting | Bulk: run failed. Streaming: held with retry, backlog counted | Dropped deliveries; regenerated-and-duplicated deliveries |
| Gate cannot evaluate (missing consent state) | Deny, with the rule named; access.denied | Fail-open release |
| Audit chain broken | Verification reports the first bad row on the Control panel and Data Store screens | Quiet acceptance of a tampered log |
| Session identity no longer exists | Falls back to the default (least-privileged clinician) profile | A role-less or elevated ghost session |
The individual journeys — question to answer, records arriving, records leaving, draft to signature — are animated step-by-step in Data flow diagrams.
Data flow diagrams
The six journeys data makes through the AI-native platform, animated and then walked through step by step — with the audit event written at every step and the failure branches spelled out. Notice that the AI sits inside every flow, never outside the gates: this is what a platform designed for AI use of protected data looks like in motion. Dots are data on the move; a red branch is a refusal, and the refusal is always recorded, never silent. Hover over any box for a plain-English explanation.
A user asks a question. The assistant checks their role and purpose, retrieves only the records their permissions allow (the withholding gate counts what it holds back), sends those excerpts to the model, and returns an answer with citations.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | The question | A signed-in profile asks. Their identity, roles and ambient purpose of use travel with the question. The question is stored in prompt history (questions only — answers are never stored). | ai.query |
| 2 | Retrieval planning | PHI RAG selects among the tools its role's schema contains. A tool the role lacks is absent, not forbidden — the model cannot even attempt it. | — |
| 3 | The gate | Each tool call passes the same role/consent/purpose gate a screen does. Sensitive-category records the reader may not see are withheld and counted. | phi.search / phi.disclosure / analytics.query |
| 4 | Retrieval | Gate-released excerpts come back as tool results. Population tools return counts, never lists (the counts-never-lists rule). | — |
| 5 | Drafting | The foundation model (yours — this demo runs Claude Sonnet 5) writes the answer from the excerpts, at temperature 0, citing each source as [MRN-xxx · chart]. It may not characterize documents it did not retrieve. | — |
| 6 | The answer | The cited answer renders, including the withholding statement ("3 mental-health records were withheld from this view"). The reader knows what the answer could not see. | — |
Failure branches: a population-wide question pauses for a minimum-necessary confirmation before step 3; a request to enumerate a cohort is refused with the counts-never-lists rule named; retrieval disabled (Control panel) refuses at step 2 with the switch named; a model failure at step 5 reports the error — steps 1–4's audit events are already on the chain, so the trail shows exactly what was read even for a failed turn.
A bulk run asks the source EMR for its patient group, polls until ready, downloads the record files, and encrypts, stores and indexes every record.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | Kickoff | Group/[id]/$export against the source EMR, asynchronous. On Epic the group is a provisioned Group FHIR ID and the window is one run per 24 hours per client. | — |
| 1a | Rate-limit branch | A kickoff inside the window is refused by the platform, before the vendor sees it, and the refusal is itself a recorded run in the manager's history. | bulk.refused |
| 2 | Status poll | The status URL returns progress until the manifest is ready. Bulk export has no incremental mode on Epic — every run is a full re-extract. | — |
| 3 | Download | NDJSON files, one resource type per file. An interruption at any file marks the whole run failed. | — |
| 4 | Encrypt · store · index | Reference normalization, sensitivity classification at the door, encryption, indexing. Only now, and only for a clean run, does the watermark advance. | bulk.completed |
The watermark rule, precisely: the watermark is the timestamp of the last run that completed every file. A failed run leaves it untouched, so every downstream consumer — screens, the assistant, analytics — can state exactly how fresh its world is, and a half-arrived extract can never impersonate the current population. The System Administrator can release the 24-hour hold from the Control panel; the override writes system.hold_released, because an override that leaves no trace is a vulnerability, not a feature.
An export names its scope and destination, then passes the consent gate. What passes is delivered and acknowledged; what is refused is a recorded refusal, not a quiet omission.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | The request | Scope (full population / cohort / one patient), destination (target EMR, HIE, registry, payer, ROI requester), format (FHIR NDJSON or C-CDA). | — |
| 2 | The consent & redisclosure gate | Psychotherapy notes are never in scope. Part 2 content without Part 2-specific consent refuses the export. Other sensitive categories are excluded per the data-sharing agreement — excluded, and counted. | — |
| 2a | Refusal branch | The gate's no is a first-class outcome: the run appears in history as refused with its reason, exactly where an auditor will look. | export.refused |
| 3 | Packaging | The allowed set is packaged with its exclusion counts recorded — the withheld records are numbers in the run history, never a silent gap the recipient cannot see. | — |
| 4 | Delivery | On the destination's write surface. A destination with no bulk write path (NextGen) refuses at this step rather than degrading into thousands of unrequested individual writes. | export.completed |
| 5 | Acknowledgment | Streaming deliveries track acknowledged vs produced sequence. Held = queued and accounted, retried without regenerating. Paused = a governance decision that accumulates and does not leak. | — |
The one path by which generated content reaches the legal record — and the human decision standing in the middle of it.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | The material | A visit happens; ambient documentation or a summarization request produces the raw material. | ai.query + phi.disclosure |
| 2 | The draft | PHI RAG drafts the note from retrieved records, labeled as a draft, carrying its citations. | — |
| 3 | The queue | The draft waits in the signature queue. It has no write path from here — that is the signature rule, structurally. | — |
| 4 | The human | A licensed reviewer reads the draft against its citations, edits it, and decides. On signing, the content becomes the signer's — clinically and legally. | signature.committed |
| 4a | Return branch | A draft not accepted is returned or discarded. Drafts never advance by timeout, default, or batch approval. | — |
| 5 | Write-back | Only the signed note is delivered to the EMR (on Epic, a DocumentReference create), attributed to the signer. The EMR remains the legal record. | — |
A genuine vision inference over the frames: the registry's imaging-slot model describes what it can actually see, measures from the acquisition scale, and its draft waits for a licensed reader like every other draft.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | The study | A reader opens a study in the viewer; the open is a recorded disclosure, and the context strip follows the study's patient. | phi.disclosure |
| 2 | The frames | Representative frames of the series are rendered and sent to the imaging-slot model — pixels, the acquisition scale, and the problem list; never an answer key. | ai.query |
| 3 | The read | The vision model describes only what is visible, measures discrete findings in mm, names the frame each appears on, and drafts TECHNIQUE / FINDINGS / IMPRESSION. | model.inference |
| 4 | The cache | One read per study, ever: the result is cached against the study and generator version, so every later viewer reads the same draft at no model cost. | — |
| 5 | The draft | Filing the read creates an unsigned draft report on the study's patient — into the signature queue, never past it. | ai.draft_created |
The consent gate decides before one word is captured; the self-hosted listener transcribes inside the deployment; the note files to the visit's own patient and waits for a signature.
Walkthrough
| # | Step | What happens | Audit event |
|---|---|---|---|
| 1 | The gate | Before capture: is recording this visit lawful in this jurisdiction, for this modality, with this consent? An all-party state holds capture until the visit-level attestation exists. | consent.evaluated / consent.attested |
| 2 | The capture | Record / pause / stop. Audio stays inside the deployment — the listener is self-hosted, so no ASR vendor ever touches a voice and no vendor BAA exists because none is needed. | ambient.capture_opened |
| 3 | The transcript | The listener's genuine output, speaker-labeled, imperfections included — the drafting model flags garbled terms for the signer rather than guessing. | model.inference |
| 4 | The note | A SOAP draft from the transcript, filed to the visit's own patient — never to whoever is in context, never to a stand-in. Unresolvable patient → loud refusal, no draft. | ai.draft_created |
| 5 | The signature | The draft waits in the signature queue; on signing it becomes the clinician's note and only then acquires a write path. | signature.committed |
What never happens, on any of these flows
- Data released without a gate evaluating the reader, the record and the purpose — and writing the event.
- A withholding, exclusion or refusal that is invisible to the person looking at the result.
- A partial arrival or partial delivery presented as complete.
- Generated content entering the legal record without signature.committed above it in the chain.
- Psychotherapy content in any export, to any destination, under any scope.
The components these flows run across are documented in Architecture & data flows; the exact API calls are in API details.