Healthcare Cdss Patterns

1---2name: healthcare-cdss-patterns3description: Clinical Decision Support System (CDSS) development patterns. Drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), alert severity classification, and integration into EMR workflows.4origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel5version: "1.0.0"6---7 8# Healthcare CDSS Development Patterns9 10Patterns for building Clinical Decision Support Systems that integrate into EMR workflows. CDSS modules are patient safety critical — zero tolerance for false negatives.11 12## When to Use13 14- Implementing drug interaction checking15- Building dose validation engines16- Implementing clinical scoring systems (NEWS2, qSOFA, APACHE, GCS)17- Designing alert systems for abnormal clinical values18- Building medication order entry with safety checks19- Integrating lab result interpretation with clinical context20 21## How It Works22 23The CDSS engine is a **pure function library with zero side effects**. Input clinical data, output alerts. This makes it fully testable.24 25Three primary modules:26 271. **`checkInteractions(newDrug, currentMeds, allergies)`** — Checks a new drug against current medications and known allergies. Returns severity-sorted `InteractionAlert[]`. Uses `DrugInteractionPair` data model.282. **`validateDose(drug, dose, route, weight, age, renalFunction)`** — Validates a prescribed dose against weight-based, age-adjusted, and renal-adjusted rules. Returns `DoseValidationResult`.293. **`calculateNEWS2(vitals)`** — National Early Warning Score 2 from `NEWS2Input`. Returns `NEWS2Result` with total score, risk level, and escalation guidance.30 31```32EMR UI33  ↓ (user enters data)34CDSS Engine (pure functions, no side effects)35  ├── Drug Interaction Checker36  ├── Dose Validator37  ├── Clinical Scoring (NEWS2, qSOFA, etc.)38  └── Alert Classifier39  ↓ (returns alerts)40EMR UI (displays alerts inline, blocks if critical)41```42 43### Drug Interaction Checking44 45```typescript46interface DrugInteractionPair {47  drugA: string;           // generic name48  drugB: string;           // generic name49  severity: 'critical' | 'major' | 'minor';50  mechanism: string;51  clinicalEffect: string;52  recommendation: string;53}54 55function checkInteractions(56  newDrug: string,57  currentMedications: string[],58  allergyList: string[]59): InteractionAlert[] {60  if (!newDrug) return [];61  const alerts: InteractionAlert[] = [];62  for (const current of currentMedications) {63    const interaction = findInteraction(newDrug, current);64    if (interaction) {65      alerts.push({ severity: interaction.severity, pair: [newDrug, current],66        message: interaction.clinicalEffect, recommendation: interaction.recommendation });67    }68  }69  for (const allergy of allergyList) {70    if (isCrossReactive(newDrug, allergy)) {71      alerts.push({ severity: 'critical', pair: [newDrug, allergy],72        message: `Cross-reactivity with documented allergy: ${allergy}`,73        recommendation: 'Do not prescribe without allergy consultation' });74    }75  }76  return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));77}78```79 80Interaction pairs must be **bidirectional**: if Drug A interacts with Drug B, then Drug B interacts with Drug A.81 82### Dose Validation83 84```typescript85interface DoseValidationResult {86  valid: boolean;87  message: string;88  suggestedRange: { min: number; max: number; unit: string } | null;89  factors: string[];90}91 92function validateDose(93  drug: string,94  dose: number,95  route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',96  patientWeight?: number,97  patientAge?: number,98  renalFunction?: number99): DoseValidationResult {100  const rules = getDoseRules(drug, route);101  if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };102  const factors: string[] = [];103 104  // SAFETY: if rules require weight but weight missing, BLOCK (not pass)105  if (rules.weightBased) {106    if (!patientWeight || patientWeight <= 0) {107      return { valid: false, message: `Weight required for ${drug} (mg/kg drug)`,108        suggestedRange: null, factors: ['weight_missing'] };109    }110    factors.push('weight');111    const maxDose = rules.maxPerKg * patientWeight;112    if (dose > maxDose) {113      return { valid: false, message: `Dose exceeds max for ${patientWeight}kg`,114        suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };115    }116  }117 118  // Age-based adjustment (when rules define age brackets and age is provided)119  if (rules.ageAdjusted && patientAge !== undefined) {120    factors.push('age');121    const ageMax = rules.getAgeAdjustedMax(patientAge);122    if (dose > ageMax) {123      return { valid: false, message: `Exceeds age-adjusted max for ${patientAge}yr`,124        suggestedRange: { min: rules.typicalMin, max: ageMax, unit: rules.unit }, factors };125    }126  }127 128  // Renal adjustment (when rules define eGFR brackets and eGFR is provided)129  if (rules.renalAdjusted && renalFunction !== undefined) {130    factors.push('renal');131    const renalMax = rules.getRenalAdjustedMax(renalFunction);132    if (dose > renalMax) {133      return { valid: false, message: `Exceeds renal-adjusted max for eGFR ${renalFunction}`,134        suggestedRange: { min: rules.typicalMin, max: renalMax, unit: rules.unit }, factors };135    }136  }137 138  // Absolute max139  if (dose > rules.absoluteMax) {140    return { valid: false, message: `Exceeds absolute max ${rules.absoluteMax}${rules.unit}`,141      suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit },142      factors: [...factors, 'absolute_max'] };143  }144  return { valid: true, message: 'Within range',145    suggestedRange: { min: rules.typicalMin, max: rules.typicalMax, unit: rules.unit }, factors };146}147```148 149### Clinical Scoring: NEWS2150 151```typescript152interface NEWS2Input {153  respiratoryRate: number; oxygenSaturation: number; supplementalOxygen: boolean;154  temperature: number; systolicBP: number; heartRate: number;155  consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive';156}157interface NEWS2Result {158  total: number;           // 0-20159  risk: 'low' | 'low-medium' | 'medium' | 'high';160  components: Record<string, number>;161  escalation: string;162}163```164 165Scoring tables must match the Royal College of Physicians specification exactly.166 167### Alert Severity and UI Behavior168 169| Severity | UI Behavior | Clinician Action Required |170|----------|-------------|--------------------------|171| Critical | Block action. Non-dismissable modal. Red. | Must document override reason to proceed |172| Major | Warning banner inline. Orange. | Must acknowledge before proceeding |173| Minor | Info note inline. Yellow. | Awareness only, no action required |174 175Critical alerts must NEVER be auto-dismissed or implemented as toast notifications. Override reasons must be stored in the audit trail.176 177### Testing CDSS (Zero Tolerance for False Negatives)178 179```typescript180describe('CDSS — Patient Safety', () => {181  INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => {182    it(`detects ${drugA} + ${drugB} (${severity})`, () => {183      const alerts = checkInteractions(drugA, [drugB], []);184      expect(alerts.length).toBeGreaterThan(0);185      expect(alerts[0].severity).toBe(severity);186    });187    it(`detects ${drugB} + ${drugA} (reverse)`, () => {188      const alerts = checkInteractions(drugB, [drugA], []);189      expect(alerts.length).toBeGreaterThan(0);190    });191  });192  it('blocks mg/kg drug when weight is missing', () => {193    const result = validateDose('gentamicin', 300, 'iv');194    expect(result.valid).toBe(false);195    expect(result.factors).toContain('weight_missing');196  });197  it('handles malformed drug data gracefully', () => {198    expect(() => checkInteractions('', [], [])).not.toThrow();199  });200});201```202 203Pass criteria: 100%. A single missed interaction is a patient safety event.204 205### Anti-Patterns206 207- Making CDSS checks optional or skippable without documented reason208- Implementing interaction checks as toast notifications209- Using `any` types for drug or clinical data210- Hardcoding interaction pairs instead of using a maintainable data structure211- Silently catching errors in CDSS engine (must surface failures loudly)212- Skipping weight-based validation when weight is not available (must block, not pass)213 214## Examples215 216### Example 1: Drug Interaction Check217 218```typescript219const alerts = checkInteractions('warfarin', ['aspirin', 'metformin'], ['penicillin']);220// [{ severity: 'critical', pair: ['warfarin', 'aspirin'],221//    message: 'Increased bleeding risk', recommendation: 'Avoid combination' }]222```223 224### Example 2: Dose Validation225 226```typescript227const ok = validateDose('paracetamol', 1000, 'oral', 70, 45);228// { valid: true, suggestedRange: { min: 500, max: 4000, unit: 'mg' } }229 230const bad = validateDose('paracetamol', 5000, 'oral', 70, 45);231// { valid: false, message: 'Exceeds absolute max 4000mg' }232 233const noWeight = validateDose('gentamicin', 300, 'iv');234// { valid: false, factors: ['weight_missing'] }235```236 237### Example 3: NEWS2 Scoring238 239```typescript240const result = calculateNEWS2({241  respiratoryRate: 24, oxygenSaturation: 93, supplementalOxygen: true,242  temperature: 38.5, systolicBP: 100, heartRate: 110, consciousness: 'voice'243});244// { total: 13, risk: 'high', escalation: 'Urgent clinical review. Consider ICU.' }245```