AI Platform — Architecture and Governance
Purpose: Normative baseline for AI-first platform capability: orchestration, policy, privacy, audit, and safety.
Authority: Works with ARCHITECTURE_BASELINE.md, COMPLIANCE_SECURITY.md, MODULE_SHARED_STANDARDS.md, and FR-AI-### / FR-NFR-015..018 in EHR_FUNCTIONAL_REQUIREMENTS.md.
Product stance: Assistive-first — AI accelerates work under human accountability; autonomous clinical decision-making is out of scope unless a future validated CDS program is explicitly licensed and regulated.
1. Goals
- Provide a single controlled path for model and tool use (no ad-hoc vendor keys in apps).
- Enforce tenant isolation, licensing, ABAC, consent, and minimum necessary before any PHI leaves bounded contexts.
- Ensure auditability and provenance for outputs that influence or become part of the record.
- Support offline / low-connectivity deployments with explicit degrade behavior.
2. Bounded context: ai-orchestrator
Service name (recommended): ai-orchestrator
Module code (recommended): platform.ai (subject to licensing catalog alignment)
Responsibilities
- Expose only backend APIs behind Kong (no browser-to-cloud-vendor calls with shared secrets).
- Resolve effective AI policy per tenant / org node (licensing + config + ABAC call to access-policy where needed).
- Build retrieval context (RAG) from authorized internal APIs / FHIR gateway — never cross-tenant.
- Invoke model providers (hosted or on-prem) via contracted adapters; redact or structure logs per policy.
- Emit domain events for audit and analytics (see §6).
- Apply quotas, rate limits, and circuit breaking when providers fail.
Non-responsibilities
- Owning canonical clinical persistence (delegates to existing modules / FHIR owners).
- Replacing CDS regulatory pathways without explicit product/legal sign-off.
3. Modes of use (examples)
| Mode | Description | Typical persistence |
|---|---|---|
| Documentation assist | Draft text from structured context + user instructions | Draft until user accepts / signs per clinical-notes policy |
| Speech-to-text | Transcription pipeline | Same as note workflow; audio retention per policy |
| Coding / terminology assist | Suggest codes; user selects | Audit suggestion + acceptance |
| Operational analytics | Summaries over aggregated or de-identified data | No PHI in prompts where policy forbids |
| Patient-facing education | Generic or personalized within consent | Stricter consent + separate BFF rules |
Modules declare which modes they support in SPEC.md.
4. Data, residency, and subprocessors
- PHI in prompts: Only when policy allows; minimum necessary enforced via ABAC-scoped retrieval.
- Data residency: Tenant configuration MUST govern where inference runs (region, on-prem vs cloud).
- Training: Default no use of tenant PHI for vendor model training unless explicit contractual opt-in and DPIA/legal review.
- Retention: Prompt/response retention (if any) is configurable and separate from application debug logs; default no raw PHI in unstructured app logs.
5. Human oversight and clinical record
- Outputs that become part of the legal clinical record MUST follow the same sign / amend rules as the owning module (e.g. clinical notes).
- Assistive suggestions MUST be clearly labeled in UI until accepted.
- Override: Users MUST be able to reject, edit, or replace AI output without losing manual authoring paths.
6. Events (illustrative)
Subject naming MUST follow MODULE_SHARED_STANDARDS.md. Examples:
| Type | Purpose |
|---|---|
ghasi.ai.requested | Intent to invoke AI (correlation id, tenant, actor, feature key) |
ghasi.ai.completed | Successful completion (no raw PHI payload by default) |
ghasi.ai.failed | Failure / provider error (sanitized reason codes) |
ghasi.ai.output.accepted | User committed AI-assisted content to a durable artifact |
Exact subjects and payloads are specified in ai-orchestrator EVENT_MODEL.md when the service is added to the repo.
7. API and Kong
- Public clients call
/v1/ai/...(or namespaced paths) through Kong only. - Service accounts for batch/automation use separate OAuth scopes and stricter quotas.
- Tool use (function calling) is restricted to allow-listed internal endpoints (FHIR read/search, terminology, etc.) with normal authZ.
8. Offline and edge
- Cloud models: Unavailable when offline — UI MUST degrade (queue draft text locally, sync later; or block feature per policy).
- On-device models: Allowed only if security review approves device class and tenant policy enables it.
9. Safety and CDS boundary
- Non-diagnostic assist (drafting, summarization for clinician review) is the default MVP posture.
- Risk scores / alerts that could drive clinical action require explicit CDS specification, validation, and jurisdictional compliance — not implied by this document.
10. Testing and evaluation
- Contract tests on Kong routes for AI APIs.
- Red-team / prompt injection scenarios for externally exposed inputs.
- Regression sets for critical prompts (golden outputs within tolerance where applicable).
- Tenant isolation tests on retrieval paths.
See TESTING_STANDARDS.md and FR-NFR-011.
11. Module AI adoption matrix (Tier A and Tier B)
This matrix identifies specs/modules/<folder>/ bounded contexts that may use the AI orchestrator. It is planning guidance: each module still declares concrete modes in SPEC.md and TRACEABILITY_MATRIX.md per MODULE_SHARED_STANDARDS.md §13.
Tier A — First-wave / high-value assistive (implement orchestrator integration here before or alongside Tier B where product priority dictates).
| Module folder | Typical AI modes | Guardrails |
|---|---|---|
clinical-notes | Documentation assist, dictation (STT), template fill, shorten/summarize for handoff | FR-AI-004: draft vs final; sign rules unchanged |
patient-portal | Plain-language education, visit prep, navigation assist | FR-AI-007: stricter consent; no diagnostic chat without separate CDS governance |
registration | Intake wording assist, normalization hints; duplicate hints as text only | Merge/duplicate decisions stay human + deterministic rules |
orders-cpoe | Draft order language, requisition text suggestions | No auto-submit of controlled orders without explicit confirm |
requisitions-referrals | Referral letter / requisition draft assist | Human review before send |
results | Clinician-oriented trend / result narration (review only) | Does not replace lab validation or critical-value workflow |
medication-management | Interaction explanations (from existing CDS inputs), sig parsing assist | No autonomous prescribing; suggestions only |
problem-list | ICD/SNOMED suggestions from note/context | Explicit pick; no silent write to problem list |
messaging | Staff draft replies, triage / urgency tagging | No auto-send to patients without human review |
care-plans | Draft narratives, patient-friendly goal text | Accept before persistence as agreed content |
billing | Code/charge suggestions, narrative assist for bills | Human review before financial commit |
claims | Claim narrative / attachment summary assist | Human review before submit |
insurance | Eligibility or policy text summaries for staff (non-binding) | Label as assistive; verify against source systems |
virtual-care | STT, session summary draft for clinician sign-off | Same provenance as notes where stored |
Tier B — Phase 2 / optional (valuable but not required for an initial AI rollout; core workflows remain rules-based).
| Module folder | Typical AI modes | Notes |
|---|---|---|
scheduling | Natural-language slot discovery, waitlist explanations | Scheduling engine stays authoritative |
patient-chart | “Summarize for this encounter” (orchestrator + read-only FHIR retrieval) | Chart module often hosts UI; policy lives in orchestrator + ABAC |
provider-directory | Directory bios, credential blurbs for internal use | Non-clinical copy |
facility-management | Multilingual descriptions, site copy assist | Low risk |
immunizations | Patient-facing schedule explanations | Forecasting stays rule/regulatory based |
pharmacy | Counseling / label text drafts | No autonomous dispense or verification bypass |
laboratory-lis | QC hints, operational text assist | Often overlaps vendor LIS; integrate carefully |
radiology-pacs | Report draft assist in controlled workflow | Competes with PACS vendors; governance heavy |
Not listed in Tier A/B (default): Platform modules (iam, access-policy, tenant, hierarchy, licensing, audit, terminology, platform-admin), FHIR gateway, HL7 v2 interop, allergies (only thin voice→text with mandatory confirm), vitals (device-driven; optional voice entry with numeric confirm). Those modules use MODULE_SHARED_STANDARDS §13 one-line “no generative orchestration” unless a future spec explicitly adds a Tier A/B row.
12. Traceability
Every module in §11 MUST (when that module ships AI):
- Add FR-AI / AC rows to
TRACEABILITY_MATRIX.md. - Document modes, offline behavior, and acceptance rules in
SPEC.md.
Modules not using AI declare §13 compliance with a single sentence in SPEC.md until AI is scoped.