Reference Documents

Reference Documents

Select a document from the sidebar to view the full technical specification for each implementation phase. Below is an overview of the project, what each demo simulates, and the design principles that guided the build.

Project Context

This project is a Multimodal Retrieval-Augmented Clinical Decision Support (CDS) System for Liver MRI Cancer Detection. It helps radiologists by matching new patient MRI scans against a hospital's historical case database, generating structured differential diagnoses, and warning about past diagnostic errors.

The system has 5 implementation phases (0–4). The interactive demos simulate each phase's output with realistic mock data. They are designed to be shown to hospital management to demonstrate what the finished product would look and feel like.

DocumentWhat it covers
Liver CDS Implementation PlanOverall architecture, 3-layer system, technology stack, timeline
Phase 0 — MRI Preprocessing PipelineMRI preprocessing, segmentation, QA pipeline
Phase 1 — Data Foundation & Case DatabaseCase records, EHR data, de-identification, database
Phase 2 — Embedding & Retrieval PipelineEncoders, embeddings, vector search, hybrid retrieval, API
Phase 3 — VLM Reasoning LayerMedGemma VLM, prompt engineering, confidence, explainability
Phase 4 — Insights from Similar CasesInsight taxonomy, case-aware retrieval, alerts, feedback loop

What Each Demo Simulates

Phase 0 — Preprocessing Pipeline Viewer

  • Before/after slider comparing raw vs. preprocessed MRI slices (bias correction, normalization)
  • Pipeline status dashboard: cases processed, QA pass/fail rates, segmentation Dice scores
  • Segmentation overlay: liver region in blue outline, lesions highlighted in red/orange
  • Axial slice scroller (simulated scrolling through a volume)

Phase 1 — Case Database Explorer

  • Searchable/filterable case table (filter by lesion type, LI-RADS, demographics, data source)
  • Case detail view: thumbnail, demographics, labs, annotation summary, completeness score
  • Data completeness heatmap: rows = cases, columns = data fields, colored by availability
  • Class distribution charts (lesion types, LI-RADS categories, benign vs. malignant)
  • Visual contrast: public dataset cases (~50% complete) vs. hospital cases (~90% complete)

Phase 2 — Retrieval & Embedding Visualization FLAGSHIP

  • Select a case → see top-5 similar historical cases side-by-side
  • Each retrieved case: thumbnail, diagnosis, LI-RADS, similarity score, key stats, explanation
  • 3D embedding scatter plot (UMAP) colored by lesion type, query case highlighted with lines to neighbors
  • Retrieval quality metrics bar chart (P@5, nDCG, MRR) — dense vs. sparse vs. hybrid comparison

Phase 3 — VLM Reasoning Panel

  • Split panel: retrieved cases (left) + VLM structured reasoning (right)
  • Structured differential diagnosis with confidence bars per diagnosis
  • LI-RADS assessment card with step-by-step feature checklist
  • Simulated Grad-CAM heatmap overlay on an MRI slice
  • Confidence/uncertainty indicator (green/amber/red gauge)
  • Comparison table: query case features vs. each retrieved case

Phase 4 — Insights from Similar Cases KEY DIFFERENTIATOR

  • Same retrieval view as Phase 2, but enriched with insights from historically corrected diagnoses
  • Insight cards: amber (NOTE) and red (IMPORTANT) banners surfacing lessons from similar past cases
  • “Key finding” callout pointing to a specific region on the MRI where a distinguishing feature was previously overlooked
  • Before/after toggle: retrieval results without case insights vs. with case insights
  • Learning dashboard: insights captured over time, clinician usefulness ratings trending up, patterns discovered
  • Clinical impact metrics: “12 cases enriched with insights, 8 found useful, 3 assessments refined”

Design Principles

The demos follow a clinical/medical UI aesthetic — think hospital PACS viewer or radiology workstation.

Color Palette

RoleValueSample
Background#FFFFFF / #F8F9FA
Primary text#1A1A2E
Accent (teal)#2A7B9B
Success / benign#28A745
Warning / amber#CC8400
Critical / malignant#C0392B
Borders#DEE2E6

Key Conventions

  • Typography: System fonts (-apple-system, Inter, Segoe UI). Font weight for hierarchy, not color gradients.
  • Layout: Dense, information-rich panels. Radiologists are used to seeing a lot of data at once.
  • Borders: 1px solid borders on cards and panels — medical UIs use clear boundaries.
  • Shadows: Subtle only (box-shadow: 0 1px 3px rgba(0,0,0,0.08)).
  • Status indicators: Small colored dots or pills, not large colored backgrounds.
  • Icons: Minimal and functional. No decorative illustrations.

Visual Reference Points

  • A Bloomberg terminal (dense, professional, data-rich)
  • A radiology PACS viewer (clinical, functional, dark-on-light)
  • GitHub’s issue tracker (clean, readable, structured)

Technical Approach

  • Each demo is a single self-contained HTML file with inline CSS and JS — no build step required.
  • Built with vanilla HTML/CSS/JS (no framework dependencies).
  • Mock data uses real medical terminology: LI-RADS categories, AFP/ALT lab values, Couinaud liver segments, actual lesion type names (HCC, hemangioma, FNH, cholangiocarcinoma, metastasis, cyst).
  • MRI slices are procedurally generated on <canvas> — grayscale elliptical anatomy with simulated lesion spots.
  • Interactive elements: filters filter, sliders slide, clicking a case shows details, tabs switch views.
  • Simulated processing latency with spinners where appropriate (“Generating reasoning…”).

Mock Data Parameters

CategoryDetails
Patient demographicsAges 45–75, mix of M/F, realistic liver disease profiles
Lab valuesAFP (3–400 ng/mL), ALT (20–200 U/L), platelets (50–300 ×10³/µL)
Lesion typesHCC, hemangioma, FNH, cholangiocarcinoma, metastasis, cyst
LI-RADSDistribution skewed toward LR-3/4/5 (the diagnostically interesting cases)
Case IDsFormat: CASE-2024-001, CASE-2023-147
Similarity scores0.60–0.95 range (not all 0.99)
Error cases2–3 realistic scenarios (e.g., missed washout → delayed HCC diagnosis)