Coding & CDS

FK Relationship Diagram

erDiagram
    Patient ||--o{ Diagnosis : "diagnosed with"
    Encounter ||--o{ Diagnosis : "documented during"
    CodeSetVersion ||--o{ Diagnosis : "coded using"
    Patient ||--o{ Procedure : "receives"
    Encounter ||--o{ Procedure : "performed during"
    CodeSetVersion ||--o{ Procedure : "coded using"
    CodeSet ||--o{ CodeSetVersion : "versioned as"
    CodeSetVersion ||--o{ CodeMapping : "maps from"
    CodeSetVersion ||--o{ CodeMapping : "maps to"
    CdsRule ||--o{ CdsHookEvent : "fires"
    Patient ||--o{ CdsHookEvent : "context for"
    Encounter ||--o| CdsHookEvent : "during"
    User ||--o{ CdsHookEvent : "received by"
  

CDS Hooks Evaluation Flow

graph TD
    A[EHR Trigger Event] --> B{Hook Type}
    B -->|patient-view| C[Load patient context]
    B -->|order-sign| D[Load order context]
    B -->|order-select| D
    B -->|encounter-discharge| E[Load encounter context]
    B -->|medication-prescribe| F[Load Rx context]
    B -->|problem-list-item-create| G[Load problem context]
    C --> H[CDS Rule Engine]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[Evaluate CQL / JSON-Logic expressions]
    I --> J{Rules matched?}
    J -->|No| K[No cards returned]
    J -->|Yes| L[Generate CDS Hooks response cards]
    L --> M[Return cards to EHR]
    M --> N{Clinician action}
    N -->|accepted| O[Apply suggestion]
    N -->|overridden| P[Log override + reason]
    N -->|dismissed| Q[Log dismissal]
    N -->|timed-out| R[Log timeout]
    O --> S[CdsHookEvent record]
    P --> S
    Q --> S
    R --> S
  

Functional Requirements

1. P0 The system shall store Diagnoses with dual coding (ICD-10-CM + SNOMED CT) linked to active CodeSetVersions.
2. P0 The system shall store Procedures with CPT, HCPCS, up to 4 modifiers, E&M level, and MDM rationale.
3. P0 The system shall flag AI-augmented procedures with IsAiAugmented per CY2026 AMA guidelines.
4. P0 The system shall evaluate CDS rules at each CDS Hooks trigger point (patient-view, order-sign, order-select, encounter-discharge, medication-prescribe, problem-list-item-create).
5. P0 The system shall return CDS Hooks response cards with severity (info, warning, critical) and actionable suggestions.
6. P0 The system shall log every CDS rule firing as a CdsHookEvent with clinician action (accepted, overridden, dismissed, timed-out).
7. P0 The system shall require an override reason when a clinician overrides a critical-severity CDS card.
8. P0 The system shall flag chronic diagnoses (IsChronic) with HCC categories for annual risk-adjustment re-capture.
9. P0 The system shall flag AI-powered CDS rules with IsAiDsi and link to a ModelCardUri per HTI-1 DSI requirements.
10. P1 The system shall manage CodeSet, CodeSetVersion, and CodeMapping records for annual code set updates (ICD-10-CM FY rollover, CPT annual release).
11. P1 The system shall provide cross-walk mappings (equivalent, broader, narrower, inexact, retired-no-replacement) between code set versions.
12. P1 The system shall support OrderSets triggered by diagnosis codes containing FHIR R4 order stubs.
13. P2 The system shall provide a CDS analytics dashboard showing override rates, alert fatigue metrics, and rule effectiveness by kind.

Non-Functional Requirements

• Latency: CDS rule evaluation must complete within 500 ms to avoid workflow disruption (CDS Hooks spec target).
• Throughput: Support 100 concurrent CDS evaluations per organization during peak charting hours.
• Code Set Size: CodeMapping table must handle 500K+ cross-walk records without query degradation (< 100 ms lookup).
• Audit Trail: Every diagnosis/procedure mutation and CDS event is immutably logged with actor and timestamp.
• HIPAA: All clinical data encrypted at rest (AES-256) and in transit (TLS 1.2+).
• Retention: Diagnosis and procedure records retained for minimum 7 years; CDS event logs for 3 years.

icApplication Overrides

How the Coding & CDS noun-apps generate from AMI: module-specific stack additions, project layout, override component bindings, worked Cosmos container definitions, a versioning worked example, environment cascade, and RBAC enforcement.

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:

Project directory layout P0

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

modules/coding-cds/
├── ami/
│   ├── Diagnosis.ami.json
│   ├── Procedure.ami.json
│   ├── OrderSet.ami.json
│   ├── CdsRule.ami.json
│   ├── CodeSet.ami.json
│   ├── CodeSetVersion.ami.json
│   ├── CodeMapping.ami.json
│   └── CdsHookEvent.ami.json
├── api/                  (generated; do not edit)
│   ├── Diagnosis.controller.ts
│   ├── Procedure.controller.ts
│   ├── OrderSet.controller.ts
│   ├── CdsRule.controller.ts
│   ├── CdsHookEvent.controller.ts
│   └── codeset/...       (read-only generated controllers)
├── cds/
│   ├── service.ts                  (CDS Hooks 2.0 service entrypoint)
│   ├── hooks/
│   │   ├── patient-view.ts
│   │   ├── order-sign.ts
│   │   ├── medication-prescribe.ts
│   │   ├── problem-list-item-create.ts
│   │   └── encounter-discharge.ts
│   ├── eval/
│   │   ├── cql-runtime.ts
│   │   ├── json-logic-runtime.ts
│   │   └── override-tracker.ts
│   ├── checks/
│   │   ├── ddi.ts
│   │   ├── drug-allergy.ts
│   │   ├── drug-disease.ts
│   │   └── dose-range.ts
│   └── em-leveler/                 (E/M MDM-based level prediction)
│       ├── mdm-rationale.ts
│       └── leveler.ts
├── coding/
│   ├── icd10-suggester.ts
│   ├── cpt-suggester.ts
│   ├── hcpcs-suggester.ts
│   ├── modifier-suggester.ts
│   └── hcc-recapture.ts
├── components/                     (UI bindings)
│   ├── ic-ng21-cds-suggestion-card/
│   ├── ic-ng21-cds-code-picker/
│   ├── ic-ng21-cds-em-leveler/
│   ├── ic-ng21-cds-orderset-applier/
│   └── ic-ng21-cds-override-reason-picker/
├── db/
│   ├── container-definitions/     (Cosmos container definitions emitted from AMI)
│   ├── container-policies/        (Cosmos partition-key isolation for org-scoped tables)
│   └── seed/                      (platform-default CdsRule seeds)
├── tests/
│   ├── unit/
│   ├── integration/
│   └── replay/                    (deterministic replay corpus)
└── package.json

Coding & CDS code-gen details

The CDS Hooks 2.0 service is built alongside the generated services and deployed in the same cascade.

Component bindings P0

Default AMI-type bindings are listed in the IC Reference. Module-specific overrides are below.

Worked Cosmos container definitions (org-scoped CdsRule) P1

Emitted by the IC generator from CdsRule.ami.json. Types follow the Cosmos AMI mapping. Partition key isolates by OrganizationID.

CREATE TABLE cds_rule (
  cds_rule_id              UUID         PRIMARY KEY,
  rule_family_id           UUID         NOT NULL,
  name_string100           VARCHAR(200) NOT NULL,
  hook_type_string50       VARCHAR(64)  NOT NULL,
  rule_kind_string50       VARCHAR(32)  NOT NULL,
  severity_string50        VARCHAR(16)  NOT NULL,
  expression_text          TEXT         NOT NULL,
  version_string50         VARCHAR(64)  NOT NULL,
  effective_datetime_utc   TIMESTAMPTZ  NOT NULL,
  retired_datetime_utc     TIMESTAMPTZ  NULL,
  override_threshold_decimal Decimal (JSON number) NULL,
  is_ai_dsi_bool           BOOLEAN      NOT NULL DEFAULT false,
  model_card_uri_string200 TEXT         NULL,
  organization_id           UUID         NOT NULL,
  updated_datetime_utc      TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_by_user_id        UUID         NOT NULL,
  deleted_datetime_utc      TIMESTAMPTZ  NULL
);

CREATE INDEX cds_rule_org_active_idx
  ON cds_rule (organization_id, rule_family_id, effective_datetime_utc DESC)
  WHERE deleted_datetime_utc IS NULL AND retired_datetime_utc IS NULL;

-- Partition key: /organization_id (Cosmos container partition key for org isolation)
-- All queries automatically scoped to the request context's OrganizationID partition

Global tables (Diagnosis, Procedure, CodeSet, CodeSetVersion, CodeMapping) omit OrganizationID and do not use OrganizationID partition key. Authorization on Diagnosis / Procedure is enforced at the application layer via the patient-scoped authorization-chain trace and the read-access audit; DB-layer partition key would falsely partition global data. This is documented as DEC-RH-002.

Versioning · worked example for a CdsRule break P0

Versions follow the IC break.feature.bug.buildtimestamp scheme. Every change to a CdsRule creates a new immutable row; the prior row is retired with RetiredDateTimeUTC. The active version per (OrganizationID, RuleFamilyID, t) is the one with the highest EffectiveDateTimeUTC ≤ t and a null RetiredDateTimeUTC.

Permission gating (IC hard rule #5). The break in step 3 cannot ship without the compliance.lead or practice.admin role; the build pipeline rejects break-bumps lacking the role's signed approval marker.

Coding & CDS environment details

• Dev: ephemeral; scale-to-zero; mock terminology server with a fixture subset; license-bearing code sets (CPT, SNOMED-CT) are not present.
• QA: auto-deployed on green Dev; full terminology server with non-prod tokens; replay corpus runs as a release gate.
• UAT: design-partner facing; production terminology entitlements; rule promotions captured to an audit log.
• Prod: production terminology entitlements; CDS service replicas across ≥ 3 availability zones; Object-Lock S3 retains all CdsHookEvent payloads beyond the row's TTL.

Coding & CDS RBAC notes

• SMART on FHIR scopes. Patient scopes (patient/Diagnosis.read) limit reads to the authenticated patient's own rows. Compliance writes (CdsRule, OrderSet) require the compliance.lead or practice.admin role plus AAL2 step-up.
• Global clinical-fact authorization. Global tables (Diagnosis, Procedure) are not partition-key isolated; their authorization is enforced by the patient-scope chain at the application layer (see Data Model).

Cross-Module Links

• Clinical Documentation — Diagnosis and Procedure link to Encounter; problem-list changes fire CDS hooks.
• Eligibility — Diagnosis and procedure codes feed PriorAuth service/diagnosis fields.
• Scheduling — VisitType maps to default E&M level; HCC re-capture flagged at annual visits.
• eRx / EPCS — medication-prescribe hook fires DDI, drug-allergy, drug-disease, and dose-range CDS rules.
• Revenue Cycle Management — Procedure codes and E&M levels feed charge capture and claim generation.
• Task Management — Overridden CDS alerts may generate follow-up tasks for quality review.

See also: Coding & CDS walkthrough · IC Reference