Skip to content

Architecture Decisions

Current System State

Protocol Manager is a MkDocs Material static site hosted on GitHub Pages. It serves CT protocol documentation for a single institution. There is no backend server. All data lives in Markdown files with YAML front matter under docs/ct/. The comparison tool and acquisition diagrams are vanilla JS running entirely in the browser. CI auto-generates the comparison index and sitemap JSON on every push to main.

What Was Built

CT Protocol Pages

  • Markdown files with YAML front matter (injected by extract_to_frontmatter.py)
  • Each protocol has: clinical summary, patient prep, contrast/injection parameters, series acquisition table, technical parameters, post-processing, and an SVG acquisition diagram
  • Body areas: abdomen, chest, cardiac/vascular, neuro, head/neck, extremities

Protocol Comparison Tool

  • Side-by-side protocol comparison at /compare/
  • Index pre-generated by generate_comparison_index.py from YAML front matter
  • Vanilla JS reads protocol-comparison-index.json at runtime
  • Deep linking: URL query params (?p=<filepath>&p=<filepath>) let users share comparison views

SVG Acquisition Diagrams

  • Custom SVG renderer replacing Mermaid Gantt charts (removed April 2026)
  • acquisition-diagram.js reads YAML front matter series data and renders inline SVG timelines
  • Supports multi-phase protocols, split boluses, multiple FOVs

Sitemap for radiology-agent Chrome Extension

  • generate_sitemap.py outputs docs/javascripts/sitemap.json
  • Used by the radiology-agent Chrome extension to discover protocol URLs without cross-repo pushes

What Was Abandoned and Why

FastAPI + ChromaDB + OpenAI RAG Backend

  • What it was: A Python FastAPI server that embedded protocol/guideline Markdown into ChromaDB and answered clinical questions via GPT-4o-mini RAG.
  • Why abandoned: Explicitly de-scoped. Protocol Manager's purpose is static reference documentation — a chatbot adds maintenance overhead (API keys, server costs, cold-start latency) for marginal value. AI-assisted queries are handled by the radiology-agent Chrome extension using the sitemap as a discovery layer.
  • Removed: April 2026. Entire backend/ directory, root chroma_db/, and tests/ deleted.
  • Don't re-suggest: Do not add a backend API, vector database, or OpenAI integration to this repo.

Mermaid Gantt Diagrams

  • What it was: Protocol acquisition timelines rendered as Mermaid Gantt charts embedded in Markdown.
  • Why removed: Inaccurate for CT timing (dateFormat forced representation that didn't match actual scan phases), hard to maintain, visually poor in dark mode.
  • Replaced by: Custom SVG acquisition diagrams (see above).

Protocoller (AI-assisted protocol selector)

  • What it was: A JS UI where the user entered a clinical indication and the backend returned matching protocol suggestions.
  • Why abandoned: Depended on the backend (removed above).
  • Possible future: A client-side protocoller reading from protocol-comparison-index.json would be feasible but is not currently planned.

Protocol Submission Form

  • What it was: A web form at /submit/ for creating new protocols via a POST to the backend API.
  • Why abandoned: Depended on the backend (removed above). Protocol creation is handled by editing Markdown files directly or running build_from_csv.py.

In Progress / Active

Protocol Combination View

  • Spec: docs/superpowers/specs/2026-03-21-protocol-combination-view-design.md
  • Status: Spec approved, implementation plan not yet written (as of April 2026)
  • What it is: A view in the comparison tool showing how two selected protocols could be run together in one visit — combined contrast phases, merged acquisition schedule