Clinical Documentation

FK Relationship Diagram

erDiagram
    Patient ||--o{ Encounter : "visits"
    Provider ||--o{ Encounter : "conducts"
    Appointment ||--|| Encounter : "creates"
    Encounter ||--o{ EncounterNote : "documented by"
    User ||--o| EncounterNote : "signs"
    Patient ||--|| ProblemList : "has"
    ProblemList ||--o{ Problem : "contains"
    Encounter ||--o| Problem : "first added in"
    Encounter ||--o{ ScribeSession : "recorded during"
    User ||--o{ ScribeSession : "started by"
    ScribeSession ||--o{ ScribeUtterance : "transcribed into"
    User ||--o| ScribeUtterance : "spoken by"
    ScribeSession ||--o{ ScribeStructuredOutput : "generates"
    ScribeUtterance ||--o{ ScribeStructuredOutput : "evidence from"
    ScribeUtterance ||--o{ ScribeStructuredOutput : "evidence to"
    ScribeStructuredOutput ||--o{ ScribeReviewState : "reviewed as"
    User ||--o{ ScribeReviewState : "reviewed by"
  

Scribe Provenance Pipeline

Every AI-generated clinical proposal maintains a full chain of provenance from raw audio to the final written-back entity.

graph TD
    A[Audio Stream] --> B[ScribeSession]
    B --> C[ASR Engine]
    C --> D[ScribeUtterance 1..N]
    D --> E[LLM Structured Extraction]
    E --> F[ScribeStructuredOutput]
    F -->|ModelName + ModelVersion| G[DSI Transparency Label]
    F -->|EvidenceUtteranceFrom/To| D
    F --> H{Clinician Review}
    H -->|accept| I[ScribeReviewState: accept]
    H -->|accept-edited| J[ScribeReviewState: accept-edited]
    H -->|reject| K[ScribeReviewState: reject]
    H -->|defer| L[ScribeReviewState: defer]
    I --> M[Write-back to EncounterNote / Problem / etc.]
    J --> M
    M -->|WrittenBackEntityID| N[Target Entity]
  

Functional Requirements

1. P0 The system shall create Encounters from completed Appointments with type, status, and provider linkage.
2. P0 The system shall support SOAP and APSO note formats with draft/in-review/signed/corrected/retracted lifecycle.
3. P0 The system shall version EncounterNotes using break.feature.bug.buildtimestamp format, preserving all prior versions.
4. P0 The system shall maintain a longitudinal ProblemList per patient (1:1) with SNOMED CT + ICD-10-CM dual coding.
5. P0 The system shall track Problem verification status (provisional, confirmed, refuted, entered-in-error) and clinical status (active, inactive, resolved).
6. P0 The system shall capture patient consent (verbal-recorded, written, or portal-pre-consent) before starting any ScribeSession.
7. P0 The system shall transcribe audio into ScribeUtterances with speaker diarization, BCP-47 language codes, and ASR confidence scores.
8. P0 The system shall generate ScribeStructuredOutputs from utterances with full provenance (evidence utterance range, model name/version, DSI flag).
9. P0 The system shall require clinician review (accept/accept-edited/reject/defer) of every ScribeStructuredOutput before write-back.
10. P0 The system shall write back accepted ScribeStructuredOutputs to target entities (EncounterNote, Problem, etc.) and record WrittenBackEntityID.
11. P1 The system shall support undo of accepted scribe outputs within a configurable window (default 5 minutes).
12. P1 The system shall enforce audio retention policies (default 365 days, max 3650) with automated purge.
13. P2 The system shall provide a scribe accuracy dashboard showing accept/reject rates, edit frequency, and confidence calibration per model.

Non-Functional Requirements

• Latency: Scribe structured output must appear within 5 seconds of utterance end for real-time assist.
• Audio Storage: Audio blobs stored in HIPAA-compliant blob storage with encryption at rest; retention enforced by lifecycle policy.
• HIPAA: All clinical text (notes, transcripts, problems) encrypted at rest (AES-256) and in transit (TLS 1.2+).
• DSI Compliance: Every ScribeStructuredOutput must carry ModelName + ModelVersion per ONC HTI-1 Decision Support Intervention requirements.
• Concurrency: Support 20 simultaneous scribe sessions per organization without ASR degradation.
• Audit Trail: Every note status change, problem mutation, and scribe review action is immutably logged.
• Retention: Clinical notes and problem lists retained for minimum 7 years; encounter records for 10 years.
• Accessibility: Note editor must meet WCAG 2.1 AA; scribe review UI must be keyboard-navigable.

icApplication Overrides

Stack, project layout, naming, default and override component bindings for scribe-specific surfaces, versioning with worked example, environment cascade, and RBAC enforcement.

Canonical Framings (binding for this module) P0

Technology Stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

LLM/ASR vendor independence: the platform binds against IScribeTranscriptionProvider and IScribeStructuredExtractionProvider interfaces. Swapping vendors is a configuration change, not a code change. Every vendor signs a HIPAA BAA, and contracts include zero-retention clauses where the vendor's terms allow.

Project Directory Layout P0

This module uses a non-standard directory layout; the standard skeleton is documented in the IC Reference.

modules/clinical-doc/
├── ami/
│   ├── encounter.ami.yaml
│   ├── encounter-note.ami.yaml
│   ├── problem.ami.yaml                 (global; no OrganizationID; SourceOrganizationID)
│   ├── problem-list.ami.yaml            (global; no OrganizationID; SourceOrganizationID)
│   ├── scribe-session.ami.yaml
│   ├── scribe-utterance.ami.yaml
│   ├── scribe-structured-output.ami.yaml
│   └── scribe-review-state.ami.yaml
├── api/
│   ├── EncounterController.cs
│   ├── EncounterNoteController.cs
│   ├── ScribeSessionController.cs
│   ├── ScribeReviewController.cs
│   └── ProblemListController.cs
├── domain/
│   ├── Scribe/
│   │   ├── IScribeTranscriptionProvider.cs
│   │   ├── IScribeStructuredExtractionProvider.cs
│   │   ├── ScribeOrchestrator.cs
│   │   └── ScribeWriteBackService.cs
│   └── ClinicalRecord/
│       ├── ProblemListService.cs        (cross-org global write path)
│       └── EvidenceLinkService.cs
├── container-definitions/
│   ├── encounter.json
│   ├── encounter-note.json
│   ├── problem.json                      (no OrganizationID partition; SourceOrganizationID)
│   ├── problem-list.json                 (no OrganizationID partition; SourceOrganizationID)
│   ├── scribe-session.json
│   ├── scribe-utterance.json
│   ├── scribe-structured-output.json
│   ├── scribe-review-state.json
│   └── container-policies.json          (org-scoped containers only)
├── ui-angular/
│   ├── ic-ng21-clindoc-encounter-shell/
│   ├── ic-ng21-clindoc-previsit-briefing/
│   ├── ic-ng21-clindoc-soap-editor/
│   ├── ic-ng21-clindoc-apso-editor/
│   ├── ic-ng21-scribe-audio-capture/
│   ├── ic-ng21-scribe-transcript-viewer/
│   ├── ic-ng21-scribe-review-panel/
│   ├── ic-ng21-scribe-writeback-action/
│   ├── ic-ng21-scribe-evidence-link-player/
│   └── ic-ng21-clindoc-version-diff/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e-cypress/
└── ic-application.json                  (generator manifest)

Clinical Documentation component naming

For this module: ic-ng21-clindoc-* for general clinical-documentation surfaces and ic-ng21-scribe-* for scribe-specific surfaces.

Domain-Specific Override Bindings (Scribe surfaces) P1

The Clinical Documentation module registers override bindings for fields where the default scalar component is insufficient. These overrides are declared in ic-application.json:

DDL Example — Cosmos Container Mapping P0

Generated from problem-list.ami.yaml. Note the absence of OrganizationID in the partition key and the presence of SourceOrganizationID per DEC-RH-002.

// container-definitions/global-clinical-facts.json (generated; do not hand-edit)
{
  "container": "global-clinical-facts",
  "partitionKey": { "paths": ["/PatientID"], "kind": "Hash" },
  "indexingPolicy": {
    "includedPaths": [
      { "path": "/PatientID/?", "indexes": [{ "kind": "Hash", "dataType": "String", "precision": -1 }] },
      { "path": "/SchemaVersionString50/?", "indexes": [{ "kind": "Range", "dataType": "String", "precision": -1 }] },
      { "path": "/SourceOrganizationID/?", "indexes": [{ "kind": "Hash", "dataType": "String", "precision": -1 }] }
    ],
    "excludedPaths": ["/\"DeletedDateTimeUTC\"/?"]
  },
  "entities": ["Problem", "ProblemList"]
}

// No partition-key isolation on OrganizationID for global container;
// access is enforced at application layer via read-access audit
// and authorization-chain trace (DEC-RH-007).

Contrast with the org-scoped encounter_note:

// container-definitions/org-encounter.json (generated)
{
  "container": "org-encounter",
  "partitionKey": { "paths": ["/OrganizationID"], "kind": "Hash" },
  "indexingPolicy": {
    "includedPaths": [
      { "path": "/OrganizationID/?", "indexes": [{ "kind": "Hash", "dataType": "String", "precision": -1 }] },
      { "path": "/EncounterID/?", "indexes": [{ "kind": "Hash", "dataType": "String", "precision": -1 }] },
      { "path": "/UpdatedDateTimeUTC/?", "indexes": [{ "kind": "Range", "dataType": "String", "precision": -1 }] }
    ],
    "excludedPaths": ["/\"DeletedDateTimeUTC\"/?"]
  },
  "entities": ["Encounter", "EncounterNote", "EncounterChiefComplaint"]
}

// Org-scoped container: partition-key isolation on /OrganizationID ensures
// each practice sees only its own encounter data.

Versioning — Worked Example for ProblemList Schema Bump P0

IC convention: break.feature.bug.buildtimestamp. break increments on incompatible changes (column drop or rename, type narrowing); feature increments on additive changes (new column, new index); bug increments on bug-fix-only churn; buildtimestamp is the UTC build clock.

Suppose ProblemList ships at v1.0.0.20270115T1200Z. A subsequent feature adds a PatientReviewedDateTimeUTC field to record when the patient last reviewed their own list. This is an additive change.

The Cosmos DB pattern is to deploy a backwards-compatible container at the previous major (global-clinical-facts-v1) so existing API consumers continue to read the prior shape during the rollover window. The SchemaVersionString50 on each document records the schema active at write time.

Clinical Documentation environment details

Clinical Documentation RBAC notes

• Global clinical facts. Cosmos partition-key isolation is not applied to global containers (Problem, ProblemList) — see DEC-RH-007. The ProblemListService wraps every read of a global clinical fact in an authorization-chain check and a read-access audit emission.
• Tier-3 actions. Compliance read-only of drafts; break-glass cross-org reads require WebAuthn step-up authentication and produce a tier-3 audit row.

Cross-Module Links

• Scheduling — Encounter created from completed Appointment; AppointmentID FK.
• Coding & CDS — Diagnosis/Procedure entities link to Encounter; CDS rules fire on problem-list changes.
• Eligibility — PriorAuth links to EncounterID for clinical justification.
• Patient Portal — Patients view signed notes and problem list via portal.
• Task Management — Unsigned notes generate tasks; scribe review items queue for provider.
• Revenue Cycle Management — Signed encounter notes feed E&M level calculation and charge capture.

See also: Clinical Documentation walkthrough · IC Reference