Interview: Replacing Mermaid Slop with Semantic SVG Architecture Diagrams

Interview with Cathryn Lavery on Systems Architecture and Visual Design

Q: Most engineers default to Mermaid or Excalidraw when documenting distributed systems in Git repositories. Why do those diagrams consistently break down in production documentation?

Answer: Mermaid relies on heavy client-side JavaScript interpreters that fail in headless environments, static site generators, and markdown previews without custom browser extensions. When teams generate release notes or distribute offline technical PDFs, Mermaid blocks routinely render as empty rectangles or unformatted code fences. Beyond runtime instability, automated graph layout algorithms produce chaotic routing paths where three simple microservices turn into a tangled knot of overlapping arrows. Excalidraw swings to the opposite extreme with loose, hand-drawn sketches that feel out of place in formal security reviews and infrastructure audit reports. During an outage investigation, engineers need clear, deterministic visuals rather than playful sketches. Standalone SVG files solve this problem because they store vector geometry natively. They render instantly in any browser, desktop viewer, or terminal preview tool without external dependencies or remote scripts.

Q: What makes editorial diagramming different from standard software architecture drawing tools?

Answer: Generic diagram tools treat every component as an identical rounded rectangle. You end up with forty pastel boxes joined by faint grey lines, giving readers zero indication where network traffic enters or where the primary state machine lives. Editorial diagramming enforces strict visual hierarchy and deliberate density limits. We cap graphic density at roughly four out of ten. If a diagram contains thirty nodes, twenty of them usually do not belong on the canvas and should be dropped. Only one or two elements receive an accent color, typically the database storage engine or the ingress security boundary where untrusted input crosses a trust boundary. Secondary components remain strictly monochrome. When an engineer reviews the architecture, their attention goes straight to the critical path instead of wandering across peripheral workers and message queues.

The most important editorial rule is deletion. Every box on an architecture diagram must earn its place, and accent colors belong strictly on the component that breaks first.

Interview: Contrast Budgets, Semantic Layers, and Zero-Dependency SVGs

Q: How do you structure an SVG workflow so agents and engineers can generate maintainable diagrams without fighting Figma?

Answer: We separate semantic behavior from geometric layout. Instead of dragging coordinates inside a heavyweight desktop editor or letting an LLM guess arbitrary vector coordinates, the generator selects from forty-four predefined layout patterns. We maintain dedicated grammars for database schemas, data pipelines, network perimeters, and sequence traces. The engineer defines components and relationships in structured text, and the local compiler computes the layout grid, font sizes, and connector paths. The result is pure, self-contained SVG wrapped in standard HTML. There are no canvas elements, no remote fonts, and no client-side scripts. You can inspect the markup with standard command-line tools, track line-by-line diffs in Git, and convert files to high-resolution raster images during automated test runs using a straightforward pipeline:

# Validate SVG XML tree and render high-resolution raster asset
python3 -c "import xml.etree.ElementTree as ET; ET.parse('architecture.svg'); print('SVG XML valid')"
rsvg-convert -f png -w 1600 architecture.svg -o architecture.png

Q: Dark mode support and responsive viewports often ruin custom SVGs across documentation sites. How does this architecture maintain consistent contrast across different display themes?

Answer: Most teams hardcode static hex values directly into SVG fill and stroke attributes. That approach breaks immediately when a documentation site switches from light mode to dark mode, leaving black text stranded on black backgrounds. We address this by declaring CSS custom properties within the root SVG element itself. The graphic defines semantic tokens for surface colors, border strokes, and typography, paired with media queries that detect user color preferences automatically. When the surrounding webpage changes themes, the SVG adapts on the fly without re-rendering or script execution. We also enforce strict contrast standards across every text layer, reserving monospace fonts for network ports, memory offsets, and API endpoints, while setting structural labels in clean sans-serif type. The diagram remains sharp and legible across mobile screens, retina monitors, and printed documentation.