Detailed system documentation

The complete reference for PHI AI — the AI-native platform for protected health data — in one place: what it is, every profile and permission, every screen, every record type in the Data Store, how the assistant works, how the audit trail works, the full architecture with its data flows, the animated flow diagrams, and every programmatic surface. Written to be read by anyone who works in or around the platform, not only engineers. Sections follow the role signed in: parts a role cannot use are not shown.

1. Purpose and positioning

PHI AI is an AI-native platform for protected health data — designed from first principles for AI as a first-class, governed consumer of the clinical, financial and behavioral-health record. It is not an AI feature bolted onto a records system: the architecture exists because AI reads this data. The role-scoped retrieval tools, the sensitivity segmentation, the purpose-of-use tagging, the hash-chained audit of every model interaction, the invariants and the signature gates are not add-ons around a database — they are the platform, built for the moment a model touches a protected record. EMRs connect to it as data planes: sources records arrive from, targets signed work delivers to.

It does three jobs:

1. It ingests. Clinical, financial and behavioral-health records arrive from source EMRs — in bulk (whole patient populations over the FHIR Bulk Data API) and in real time (admissions, discharges, lab results and payment remittance on streaming feeds) — and are encrypted, classified for sensitivity, and indexed into the Data Store, where they become AI-ready: every record carries the classification and provenance the gates need before a model may read it.
2. It answers and drafts. A retrieval-tuned AI assistant (PHI RAG) answers questions from the Data Store with citations, drafts clinical documentation, triages inboxes, abstracts quality measures, and screens cohorts — always inside the asker's role, always on the record.
3. It governs. Consent gates, sensitivity segmentation, purpose-of-use tracking, signature requirements, export controls and an append-only audit trail make every use of the data visible and every refusal a recorded event — governance designed for AI use of PHI, not retrofitted to it.

Equally important is what the platform is not:

• It is not a bolt-on. Nothing here was retrofitted onto an existing product: the data model, the gates and the audit chain were designed together, for AI use of protected data, from the first line. Signed clinical documentation still delivers to the EMR, which remains the chart of legal record — a legal reality, not an architectural dependency.
• It is not autonomous. No generated text enters a chart, and no record leaves the organization, without a human decision. Drafts wait in the signature queue; exports pass consent gates.
• It is not a medical device. It issues no diagnostic or treatment directive; every answer's basis is independently reviewable through its citations (see Compliance & responsibility).

2. Design principles

Two principles sit above everything else; five more run through every screen and every API in their service.

1. AI for PHI. The platform exists to put AI at the center of protected health data — not beside it, not bolted on after. Every design decision below is downstream of this one: the AI is a first-class, governed consumer of the record, reaching data through the same gates as people, citing what it reads, and drafting rather than deciding.
2. Compliance first. Compliance is the core design principle, not a policy layer: the rules live in the shape of the system. Population tools return counts and cannot enumerate; unsigned drafts have no write path; psychotherapy content has no export path; recording waits for the jurisdiction's consent. Where a rule can be structural, it is.
3. Minimum necessary. Every profile holds an enumerated list of permissions. A screen, record or tool outside that list does not exist for that profile — the navigation does not show it, the route refuses it, and the assistant does not hold the tool. Nothing is reachable "because the database has it."
4. Nothing silent. Every question asked of the AI, every record it reads, every export, every configuration change, every override and every refusal is appended to a hash-chained audit trail that cannot be quietly edited. When records are withheld from an answer or an export, the withholding is counted and stated, never invisible.
5. Fail closed, refuse loudly. A gate that cannot decide denies. A run that cannot finish is marked failed, never partially-complete. And a refusal is presented as a first-class outcome — in run histories, on screens, in the audit trail — because a gate that fails closed is the product, not an error condition.
6. A human signs. AI-drafted documentation is a draft until a licensed person signs it (the signature rule). Population queries return counts, never named lists, on the de-identified plane (the counts-never-lists rule).
7. Calm surfaces. The interface is designed for people who live in an EMR all day: one identity card, collapsible detail, no autoplaying anything, and a design language where color always means something — orange marks state that demands attention, green marks records arriving, navy marks reading.

3. Identity: profiles, roles and permissions

Access control is two-layered: a profile (a person) holds one or more roles, and each role grants an enumerated set of permissions. Screens and actions check permissions, never roles, so a new role can be composed without touching a single screen.

3.0 Where roles come from — and where they do not

This system is not the source of truth for users or roles, and is not intended to be. It is designed to be governed by your organization's identity source of truth — your identity provider and directory (Entra ID / Okta / LDAP or equivalent), where accounts are created, roles are assigned, access is reviewed, and departures are processed. The platform's job is enforcement, not authority:

• Identity arrives established. In the recommended deployment the platform trusts an identity your reverse proxy / SSO has already authenticated, or one a SMART-on-FHIR launch carries from the EMR. The platform authenticates nobody in that mode and stores no credential.
• Role assignments originate upstream. The roles an identity carries are asserted by your identity layer; the platform maps them to its enumerated permissions and enforces them on every route, tool and option set. Change a person's role in your directory and the platform's enforcement follows — there is no separate role store to drift out of sync.
• Local accounts are a fallback, not the design. The optional local-accounts mode exists for organizations with no identity provider at all; it is off by default, and it is the only configuration in which this platform holds a credential. If you have an IdP, use it.
• The Control panel's matrix is an enforcement view, not a user directory. It shows what each role can reach so reviews and audits have a live artifact — it is not where people are provisioned, and deliberately has no "create user" button in IdP-governed deployments.
• Reviews and deprovisioning belong to your source of truth. Access recertification, joiner/mover/leaver processing and emergency revocation all happen in your identity system; the platform reflects the result on the next request. (See Compliance & responsibility — access governance is an organizational duty this software cannot discharge.)

3.1 Profile archetypes

Profiles are composed from roles; the identities behind them come from your identity provider (§3.0). The archetypes below are the working realities the role set is designed around — this demonstration site's persona switcher signs you in as one archetype at a time. It also offers a second group that holds one role each, so every role can be inspected on its own: a composite can never show you a boundary, because its other roles keep filling the gap. Signing in as the auditor alone is how you see that an auditor is not a clinician with extras.The demonstration cast itself is documented with the rest of the synthetic environment in Emulators & non-PHI setup.

3.2 The permission matrix

Twelve permissions exist. The wildcard * (System Administrator only) grants all of them.

Three deliberate asymmetries are worth noticing, because they carry the security model:

• Psychotherapy is not a superset. Holding psychotherapy:read grants nothing else. The behavioral-health clinician profile holds Clinician and Psychotherapy; a hypothetical account holding only Psychotherapy could open a psychotherapy note and nothing besides.
• Auditor is read-only and narrow. The Auditor role holds exactly audit:read. Audit review does not require chart access, so it does not include it.
• The Administrator cannot open a chart. Operations work — connections, imports, configuration — never requires reading a patient's record, so the Administrator role does not include patient:read. When an Administrator hits a chart URL, the refusal lands in the audit trail like any other.

3.3 Refusal behavior

A request outside the profile's permissions returns HTTP 403 with a page that names the missing permission, and writes an access.denied event carrying the actor and the permission that was missing. Refusals are not exceptions to the audit trail — they are among its most useful entries, because a pattern of denials is how a privacy officer discovers someone probing beyond their role.

4. Purpose of use

Every action that touches a record carries a purpose of use, integrated into the workflow where the action happens. The five purposes mirror HIPAA's permitted-use structure:

The purpose is not decorative, and it is deliberately not a session mode — there is no ambient purpose selector, because a purpose of use is an assertion about a specific action, not a state a session sits in. It is asserted where data actually moves: the assistant collects it per question, an ROI request records its purpose at creation and every resolution of that request carries it, signature commits are treatment by definition, operations actions are operations — and where no explicit choice is called for, the default derives from the role doing the work (a clinician's reads assert treatment; records and operations roles assert operations). Every audit event stores the result, which is what lets the organization answer the two questions HIPAA's accounting and minimum-necessary rules keep asking: who touched this record, and under what claimed justification. In the deployable platform the purpose additionally travels as an IAM session tag, so even the cloud permission layer knows why a read is happening.

5. Screen-by-screen reference

5.0 Sticky patient context — the one-patient-per-screen contract

Wrong-chart errors happen when a screen shows one patient while the clinician believes they are working on another. The platform prevents this with a contract enforced by screen class, not by convention:

• Single-patient screens (chart, claim, imaging study, draft review, release review, prior authorization) synchronize the patient-context strip to the patient they render — the strip can never name a different person than the page below it. Each context move is an audited session.context event.
• Patient-linked worklists (signature queue, inbox, imaging worklist, claims queues, release requests) show only the in-context patient's items, behind one shared scope banner. Widening to all patients takes an explicit action and is recorded on the audit trail as session.scope_widened.
• Documents file to their own patient. An ambient visit note attaches to the visit's patient — never to whoever happens to be in context, and never to a stand-in. If that patient cannot be resolved, the platform refuses to draft rather than file to the wrong chart. The ambient encounter list itself is scoped like every other worklist, and opening an encounter moves the context to the visit's patient before anything renders.

Every screen is classified against this contract at build time, a runtime tripwire records any worklist that renders outside it, and the regression suite derives its coverage from the same classification — so a new screen cannot ship unclassified.

5.1 Clinical workspace

5.2 Revenue & records

5.3 Population

5.4 Integration

5.5 System

5.6 Governance

6. The Data Store

6.1 Record types

On this demonstration site the Data Store holds a fully synthetic population — no real person's data appears anywhere — with full longitudinal records. Every record class the platform can house is populated:

6.2 Sensitivity classification

At ingestion, every condition, medication and document is classified into one of five sensitive categories — or none. Classification is first-match-wins against curated terminology:

Two honest limits of the demonstration classifier, stated because a production deployment must do better: it is keyword-driven (a production system uses curated value sets — SNOMED, RxNorm, LOINC — maintained clinically), and first-match-wins means a record in two categories carries its first. The handling pipeline — withhold, count, state, refuse redisclosure — is the part the demonstration reproduces faithfully.

6.3 The psychotherapy store

Psychotherapy notes are not a sensitivity class — they are a separate store. This mirrors HIPAA's own structure, which defines psychotherapy notes as notes "separated from the rest of the individual's medical record" (45 CFR §164.501). Concretely:

• They live in their own table, never joined into chart queries.
• Only psychotherapy:read can list or open them, and the assistant requires an explicit minimum-necessary confirmation before disclosing session content even to that role.
• Every listing writes psychotherapy.list; every read writes psychotherapy.disclosure.
• No export path includes them. Not bulk, not streaming, not ROI. The export managers count them among the withheld.

6.4 The Data Store audit page

The Data Store screen renders, live on every load: per-table row counts, earliest and latest record dates per class, and six integrity checks — orphaned-reference sweeps, encounter linkage, sensitivity-classification coverage, duplicate detection, the psychotherapy separation invariant, and a full audit-chain verification. A failing check renders as a failure; the page does not average problems away.

7. The assistant (PHI RAG) in depth

7.1 The retrieval contract

PHI RAG is a retrieval-tuned system: the language model never answers about records from memory. The contract, enforced by the system prompt and the tool design together:

• Answer only from retrieved records. Every factual claim about a patient cites its source in the form [MRN-###### · chart].
• Never assert absence. The model may not claim a record does not exist or a document does not say something unless it retrieved and read that document. "Not found in what I retrieved" is the honest formulation, and the required one.
• Confirm before sweeps. A question requiring a population-wide read triggers a minimum-necessary confirmation: the assistant states what it would have to read and asks before reading.
• State the withholding. When the gate withholds sensitive records from retrieval, the answer says how many and under which rule — the reader knows the answer is incomplete and why.
• Counts, never lists. On the population plane, the assistant returns cohort sizes, not names (the counts-never-lists rule). A request to enumerate patients with a condition is refused with the invariant named.

7.2 Threads, history and saved prompts

The assistant keeps a per-session thread (the last 12 turns render; the model sees the last 6). Every question is stored per-user in prompt history — questions only, never answers, so history is a workflow convenience rather than a shadow copy of PHI. Any question can be saved for reuse; clicking a history or saved item prefills the ask box and runs nothing until the user presses Ask.

7.3 Degradation ladder

The assistant degrades in defined steps, never silently: live model with retrieval → retrieval disabled (System Administrator switch: the assistant refuses to discuss records at all and says why) → live calls off or key absent (the deterministic scripted fallback answers, labeled as such) → model call failure (the error is stated; the question was already audited; nothing was read). At no rung does it guess.

8. The audit trail

8.1 Event anatomy

Every event is one appended row: at · actor · action · resource_ref · purpose · prev_hash · event_hash. The event_hash is the SHA-256 of the event's content plus the previous event's hash, which chains the log: editing or deleting any historical row changes every hash after it, and the Control panel's verification (which re-derives the entire chain on every load) turns from intact to BROKEN with the first bad row identified.

Object references, never content: the log records that a psychotherapy note was disclosed to its treating clinician for treatment — it does not copy the note. The audit trail must be reviewable by auditors without itself becoming a PHI disclosure surface.

8.2 Event catalog

8.3 What the trail is for

Three consumers, three uses: the privacy officer answers a patient's accounting-of-disclosures request from phi.disclosure and roi.* events; the security team reads access.denied patterns and system.* overrides as its detection surface; and the auditor verifies the chain and samples events against source screens. In the deployable platform, concurrent writers can legitimately fork the chain (two processes appending at once); forks are recorded and merge verification handles them — a fork is not tampering, and verification knows the difference.

9. Configuration reference

Runtime configuration lives in the platform configuration store, editable only through audited screens:

10. Security model — the consolidated view

Each control above appears where it operates; this section is the one place they are stated together, layer by layer.

• At rest. Every stored object is envelope-encrypted before it lands: a per-object data key, wrapped by a organization-managed KMS key that never leaves the key service. Key use is logged by the cloud, so a decryption that bypassed the application would still leave evidence. The psychotherapy store is physically separate with its own access policy.
• In transit. TLS 1.2+ end to end — EMR↔platform, platform↔storage, platform↔KMS, platform↔model provider — and the storage buckets carry policies that refuse non-TLS requests rather than merely preferring encrypted ones.
• Identity & session. The application binds localhost and trusts only a reverse-proxy-established identity (your SSO), or SMART launch from the EMR, or — as the fallback — local accounts. Sessions are signed; every mutation requires the session's CSRF token; roles mirror cloud IAM roles so the application layer and the infrastructure layer cannot disagree about who may do what. The platform is not the source of truth for users and roles — your organization's identity system is.
• AI-specific controls. The model receives excerpts, never a database connection. Tool schemas are generated per role, so an unpermitted capability is absent rather than refused. Temperature 0, bounded output, a six-turn context tail — the model never accumulates unbounded PHI context. Model traffic runs inside your BAA'd cloud account (Bedrock, Vertex AI, Azure AI Foundry) or under a dedicated agreement with whichever vendor's API you call directly. None of these controls depend on which model answers — they are properties of the platform, so changing model vendors changes the answer's author and nothing about what it is allowed to see. Psychotherapy access for the assistant is a separate, default-off switch.
• Structural refusals. The controls above are not policies asking models or people to behave: population tools return counts and cannot enumerate; unsigned drafts have no write path; psychotherapy content has no export path. The refusal is in the shape of the API, not in a prompt.
• Monitoring. The hash-chained audit trail is re-verified on every Control panel load; model analytics watch drift and fire alerts that never auto-close; access.denied patterns surface probing. What the platform cannot see — your risk analysis, your BAAs, your workforce training — is enumerated in Compliance & responsibility.

11. Extensibility — frontier models, your models, your features

PHI AI is a highly configurable platform, not a fixed product. Three extension surfaces are part of the core design, and all three are managed — registered, enabled, activated, monitored and audited — through the same Control panel, never through code changes.

11.1 Every major frontier model integrates

The assistant's foundation-model slot is provider-pluggable. Out of the box it speaks three provider surfaces — the Anthropic API, AWS Bedrock and GCP Vertex AI — which between them serve the major frontier families: Claude, Gemini, Llama, Mistral and the rest of each catalog. Beyond the built-in providers, the model registry accepts any model behind an HTTPS endpoint, so Azure AI Foundry in your own tenant, a frontier model reached through your own gateway, an open-weights model you host, or a fine-tune you trained all join the same way — and a model registered that way is not a second-class citizen: it lands in the same slot, under the same audited lifecycle, with the same permissions. Which model is live is a Control panel decision: register it, enable it, activate it into the slot — every step audited — and deactivating falls back to the built-in default rather than to silence. The demo on this site happens to run Claude Sonnet 5; a deployment runs whatever you choose, under your own BAA with your AI provider.

11.2 Bring, build and extend your own models

The registry is not only for language models. Nine model kinds are first-class — foundation, retrieval, deterministic, predictive, classifier, imaging, optimization, mapper, custom — and fifteen capability slots wire them into the product: assistant, claims, prior-auth, coding, ROI, no-show, segmentation, ambient (the self-hosted speech listener), triage, scheduling, ingest, imaging, trials, measures, and other. Activate your own denial-risk model into the claims slot and the Claims & billing screen scores with your model; the built-in core steps aside but stays registered, one click from reinstatement. Every model in a slot automatically inherits the platform's management surface: lifecycle audit events, live performance metrics, drift recognition against the population it serves, and alerting that never closes itself.

11.3 Step by step: bringing your own model — with audit and tracking on

The lifecycle below is the only path a model takes into production, and it is the same for a frontier LLM behind a gateway, a vendor's risk model, and a classifier your own team trained. Following it is what enables PHI AI's required audit and tracking — a model that skips a step simply never serves a slot, so there is no untracked way in.

1. Prepare the endpoint. Expose the model behind HTTPS (the registry rejects non-TLS endpoints at registration). Decide its capability slot up front — the slot determines which feature it powers and which metrics will watch it. Your endpoint must be stateless with respect to PHI: it receives the request, returns the inference, and retains nothing — the same posture your BAA with the model's provider must cover.
2. Register it (Control panel → Model registry → Register): name, kind (foundation · retrieval · deterministic · predictive · classifier · imaging · optimization · mapper · custom), slot, provider, model ID, version, endpoint URL, and its stated purpose. Registration writes system.model_registered to the audit trail naming the model — tracking begins before the model serves anything.
3. Enable it (system.model_enabled). Enabled means eligible, not live: the slot still runs its current model. This is the state for validation against your own data.
4. Activate it into its slot (system.model_activated, recording the slot). The feature screen switches to your model immediately, and its AI-core banner says so: "activated from the registry." The built-in core steps aside but stays registered — deactivating falls back to it, never to silence. The assistant slot additionally requires kind foundation and a model ID, because that slot is live-wired to the provider API.
5. Verify the tracking took hold. Open the feature's screen, then the audit trail: every invocation of the slot now writes model.inference naming your model and version (e.g. claims/pending-queue n=25 model=YourRiskModel v2.1). Assistant questions carry model= on their ai.query events the same way. This is not optional instrumentation you add — the platform writes it at every slot invocation, whichever model is active.
6. Confirm monitoring attached. Model analytics & monitoring computes the slot's performance metrics and population-stability drift for whatever model serves it — your model inherits the watch the moment it activates. Alerts fire on the same thresholds, are acknowledged under a name (model.alert_acknowledged), and never close themselves.
7. Operate it like everything else. Disable (system.model_disabled) degrades the feature honestly with the switch named on its screen; delete (system.model_removed) requires the model be non-builtin and falls the slot back first. Every state change is an audited event under the operator's name — the model's whole life on the platform is reconstructible from the trail.

What PHI AI requires of you, summarized: a TLS endpoint, a truthful registration (kind, version, purpose), your own BAA with the model's provider for any PHI-reading slot, and validation before activation. What PHI AI guarantees in return: lifecycle audit, per-invocation model.inference attribution, live metrics, drift recognition, and alerting — for every model, built-in or brought, with no additional integration work.

11.4 Extend the features themselves

Features are built against slots and permissions, not against models or roles — which is what makes them extensible. A new feature declares the capability slot it draws from and the permission that gates its screen; the registry, monitoring, refusal and audit machinery attach to it for free. The same pattern governs what already ships: when a System Administrator disables a slot's model, that feature degrades honestly on its own screen with the switch named, and everything else keeps working. Roles compose the same way — screens check permissions, never role names, so your organization's identity system can define new roles without a code change anywhere.

11.5 The configuration surface, in one place

Everything below is live-configurable from the Control panel and the Source & target EMRs screen, and every change writes config.changed (or its own system.* event) under the operator's name:

• Models: the active model per capability slot, the assistant's live-call and retrieval switches, the answer-length bound, and the full registry lifecycle.
• Integrations: source and target EMR vendor, base URLs, client IDs, the bulk group, and each outbound feed's paused/healthy state — with independent SSO per side.
• Deployment shape: the small/large storage profile, retention periods with per-resource-type overrides, and the per-cloud infrastructure variables (all set at deploy time, all documented in Setup & deployment).
• Identity: proxy SSO, SMART launch, or local accounts — with roles asserted by your identity source of truth.

The regulatory frame for all of the above: Compliance & responsibility. Deployment sizing and infrastructure: Setup & deployment.