cs249r_book/interviews/vault/visuals/ARCHITECTURE.md

Visual question architecture

Status: active (proposed 2026-04-25, supersedes the SVG-only path described in AUTHORING.md v1)

This document is the design contract for how StaffML attaches diagrams to questions. It supersedes the implicit "all visuals are hand-authored SVG" approach that shipped with cloud-visual-001.

---

The core idea — three layers, decoupled

Layer	Concern	Owns
Website (practice page)	Render the static SVG as <img> and surface its alt + caption	visual.kind, visual.path, visual.alt, visual.caption
Build pipeline	Compile DOT or matplotlib source into the same SVG asset the website ships	visual.source_format + naming convention
Authoring	Decide whether a diagram earns its place; pick the format whose layout engine fits	AUTHORING.md rules

The website only reads the static SVG asset. It does not know — and should not know — whether the SVG was hand-drawn, compiled from DOT, or rendered by a Python script. Build provenance is metadata for maintainers and tooling, not a runtime concern.

---

YAML schema (the contract)

visual:
  kind: svg                              # what the website ships — always svg
  path: <id>.svg                         # the static SVG asset (the only thing the practice page loads)
  alt: <text, ≤250 chars>                # screen-reader description, no interpretation
  caption: <text, optional>              # small caption shown below the diagram
  source_format: dot | matplotlib | hand # OPTIONAL build metadata — default 'hand'

Why kind is always svg

kind was originally framed as the authoring format (svg / dot / matplotlib). That was a mistake: the website only ever renders SVG, and exposing the authoring format in kind: confused the website schema with the build-tool schema. The fix is to fix kind: at svg (the output format) and add source_format: (the input format) as separate, optional build metadata.

File layout — naming convention does the work

For each visual, two files may coexist:

interviews/vault/visuals/<track>/<id>.svg     # the asset the website ships (always present)
interviews/vault/visuals/<track>/<id>.dot     # iff source_format=dot     — build input
interviews/vault/visuals/<track>/<id>.py      # iff source_format=matplotlib — build input

The renderer doesn't need a separate source: field in the YAML — it infers the source filename from the SVG basename and the source_format hint. If source_format is hand (or absent), no build step runs; the SVG is the source.

---

Three supported source formats

We pick the format whose layout engine fits the content. Don't hand-author SVG when an auto-layout tool will do it for you.

source_format	Use for	Layout effort	Tool
dot	Topology, graphs, dataflow, network fabrics	Auto	dot -Tsvg (graphviz ≥ 2.40)
matplotlib	Curves, plots, Gantt charts (barh), heatmaps	Programmatic	python3 <script> then savefig
hand	Custom layouts that don't fit either above (memory-page diagrams, mixed annotations)	Manual	text editor + book SVG style guide

We considered Mermaid for sequence/Gantt diagrams. Decision: matplotlib's barh plus annotation API covers the same ground without adding a Node-based dependency. If a future archetype genuinely needs Mermaid (e.g., declarative state machines), we revisit.

When to pick which

Visual archetype	source_format	Why
Ring AllReduce / Tree AllReduce	dot	Nodes + directed edges, layout-engine-perfect
Pipeline parallelism / network fabric topology	dot	Same
Pipeline bubble Gantt / prefill-decode interleave	matplotlib (barh)	Time on x-axis, lanes on y-axis — programmatic
Roofline plot / queueing hockey-stick / scaling curve	matplotlib	Continuous functions plus annotations
KV-cache page layout / memory hierarchy data path	hand	Custom spatial composition
Duty-cycle timeline	matplotlib	Programmatic time-series
Checkpoint/recovery RPO/RTO	matplotlib (barh)	Same Gantt-like layout

Default: try DOT first for graph-shaped content; try matplotlib first for time/quantity-shaped content; fall back to hand only when neither fits.

---

Build pipeline

interviews/vault/scripts/render_visuals.py is the single entry point. It scans every question YAML's visual: block and dispatches by source_format:

source_format	Pipeline
hand (or absent)	No-op. The SVG IS the source. Just confirm it exists.
dot	dot -Tsvg <id>.dot -o <id>.svg
matplotlib	python3 <id>.py (the script reads os.environ["VISUAL_OUT_PATH"] and savefig to it)

After rendering, every output SVG passes a normalization step:

1. Strip XML comments and metadata that vary by renderer version.
2. Set <svg ... font-family="Helvetica Neue, Helvetica, Arial, sans-serif"> to match book style.
3. Confirm dimensions are reasonable (viewBox width 600–800).
4. Confirm no embedded raster (<image href="data:...">).

Normalization keeps DOT-rendered, matplotlib-rendered, and hand-authored SVGs visually consistent in the practice-page rendering.

---

Generation: Gemini in the loop

The corpus has historically been Claude-heavy. To reduce single-model bias and to scale visual coverage, we add a Gemini-driven generation pipeline mirroring the existing gemini_cli_math_review.py:

interviews/vault/scripts/gemini_cli_generate_questions.py:

1. Targets weak coverage cells from portfolio_balance_loop.py output (which track × topic × zone × level slot is under-populated).
2. Generates candidate question YAMLs, including a visual: block when the topic appears in the visual-archetype catalog.
3. For visual-eligible items, also generates the source artifact (DOT text, or a small matplotlib script) and writes it next to the YAML's expected SVG asset path. render_visuals.py then compiles it.
4. Outputs as drafts (status: draft, provenance: gemini-3.1-pro-preview). Never auto-publishes.

Cross-model validation

Gemini-generated drafts are reviewed by gemini_cli_math_review.py, which can also be run with a Claude model to provide cross-model agreement. The default flow:

• Generation: Gemini 3.1 Pro Preview drafts the question.
• Math review pass: Gemini 3.1 Pro re-checks arithmetic, units, and hardware specs against the same constants reference used during generation. (A Claude-pinned re-run is the natural follow-up for release-grade verification.)
• Visual review: a separate visual-fidelity check confirms the rendered SVG matches the scenario's claimed quantities (e.g., 4 ranks in the ring → 4 nodes in the DOT graph).

A draft promotes only if the math pass returns CORRECT and the visual check passes. Disagreements escalate to maintainer review.

---

Coverage goal

Not "N visual questions". Instead:

• Cover every topic in the visual-archetype catalog with at least one exemplar (10 archetypes today; the catalog can grow).
• For each track with applicable archetypes, ship at least 2 visual exemplars so the "Visual questions only" filter has substantive content.
• Cap visual enrichment at the level where it stops earning its place (per AUTHORING.md three-condition test).

We expect 30–80 visual-enriched published questions across the corpus once Gemini-driven generation runs against the catalog. This is a ceiling, not a target — the test is always "does this diagram earn its place".

---

Migration path

This document supersedes the AUTHORING.md assumption that all visuals are hand-authored SVG. AUTHORING.md remains the authority on when a visual earns its place; this document is the authority on how the visual is encoded and rendered.

Existing cloud-visual-001.yaml continues to work unchanged — its kind: svg, path: cloud-visual-001.svg schema is the new default, and source_format is omitted (treated as hand).

---

Open questions

• Should the rendered SVG be normalized so DOT + matplotlib + hand SVG all use the same color palette? (Probably yes — palette consistency matters more than rendering-tool fidelity.)
• Should we allow a question to attach multiple visuals (e.g., a before/after comparison)? Schema supports an array easily; UI doesn't yet.
• For Gemini-generated visuals, do we need a "diagram review" model pass beyond the math review? A multimodal LLM could verify a rendered SVG matches the YAML's claims. (Worth prototyping; not yet built.)