10. Clinical Guidelines

10. Clinical Guidelines

DIRD+ classifies severity with a guideline-agnostic engine. Clinical guidelines are JSON files, not code — adding a new country's guideline means writing a JSON and registering it, with no application changes.

• Engine: src/lib/clinical-guidelines/ (GuidelineLoader, MultiGuidelineClassifier).
• Guideline files: public/clinical-guidelines/*.json, registered in public/clinical-guidelines/index.json.
• Editor + validator in the UI: Settings, with src/lib/ai/ validation reporting structural errors and warnings on load.

Currently implemented

Guideline	Country	Scope
ICDR 2024	International	International Clinical Diabetic Retinopathy Disease Severity Scale (reference standard)
MINSAL Chile 2017	Chile	National GES protocol (Problem #31)

What a guideline JSON defines

{
  "guideline_id": "icdr_2024",
  "metadata": { "name": "ICDR International 2024", "country": "International", "status": "official" },
  "severity_levels": [
    { "id": "no_dr",     "name_es": "Sin RD Aparente", "order": 0, "color": "#22c55e" },
    { "id": "mild_npdr", "name_es": "RDNP Leve",       "order": 1, "color": "#84cc16" }
  ],
  "classification_rules": [
    { "severity": "mild_npdr", "conditions": ["microaneurysms_only"], "logic": "AND", "priority": 1 }
  ],
  "rule_421": {
    "enabled": true,
    "criteria": ["extensive_hemorrhages_4q", "venous_beading_2q", "irma_1q"]
  },
  "treatment_protocols": [
    { "severity": "severe_npdr", "urgency": "accelerated",
      "actions": ["referral_ophthalmology", "retinal_imaging"], "followup_interval_days": 30 }
  ],
  "class_mapping": {
    "microaneurysms": ["microaneurysm", "microhemorrhages"],
    "hemorrhages":    ["hemorrhage"],
    "hardExudates":   ["hard_exudate"],
    "softExudates":   ["cotton_wool_spot"],
    "neovascularization": ["neovascularization"]
  }
}

Block	Purpose
severity_levels	Ordered grades (no DR → mild → moderate → severe → proliferative) with display metadata
classification_rules	Conditions that map detected lesions to a severity level
rule_421	The ICDR 4-2-1 rule for severe NPDR (4-quadrant hemorrhages, venous beading in 2, IRMA in 1)
treatment_protocols	Per-level clinical actions, urgency, and follow-up interval (days)
class_mapping	Maps model classes (page 09) to the guideline's clinical categories

Spatial analysis

The engine evaluates lesions per quadrant (4 zones + macular center) so it can apply spatial criteria such as the 4-2-1 rule automatically. Specialized detectors in src/lib/analysis/ (hemorrhages, microaneurysms, macular edema, cup/disc) feed this step.

Human correction

The clinician can override the generated classification. When they do, the record is flagged manuallyModified: true so the correction is fully traceable.

Adding a guideline

1. Create public/clinical-guidelines/my_guideline.json following the schema above.
2. Register it in public/clinical-guidelines/index.json.
3. Reload — the app detects it automatically. No code changes, no recompilation.