Harrison Halperin
Designer & builder

Diagram Generator

Diagrams as compiled artifacts

Harrison Halperin

Project brief

Shipped

Problem

Architecture diagrams drift when they are redrawn by hand instead of compiled from structured relationships.

Outcome

A pipeline that compiles a JSON relationship dictionary deterministically into Mermaid and SVG, when the architecture changes, the diagram is regenerated, not redrawn.

Evidence

  • The pipeline parses the rendered SVG back into geometry (node boxes, edge paths) and computes layout metrics like overlaps, density, and edge lengths, turning “does this diagram look good?” into regression-checkable numbers.
  • A test-analyze-fix loop experiments in sandboxed runs and promotes a candidate only when its metrics pass.
  • Dual channels and rule layers (July 2025) is the earlier context architecture behind keeping scaffolding out of the main thread.

Key decisions

  • Source zone: The ARD JSON file is the only source of truth. Diagrams are never hand-edited.
  • Build zone: Mermaid, SVG, and HTML exports come from one deterministic build, so diffs stay clean.
  • Measure zone: Rendered SVG is parsed back into geometry, turning diagram quality into regression-checkable numbers.
  • Optimization zone: A tester, analyzer, and fixer iterate in sandboxes. A candidate promotes only when its metrics pass.

Source to artifact

The first figure follows one architecture description from ARD JSON to a measured, exported diagram.

ARD to measured diagram
01
ARD JSONnodes + edgessource of truth
02
Normalizestructural analysisvalidated against schema
03
BuildMermaid + iconsdeterministic ordering
04
ExportSVG · HTML · Markdownrendered artifacts
05gate
Measurelayout metricsoverlaps, density, edge length
The ARD JSON file is the only source of truth. It normalizes, builds, exports, and gets measured on every run.

I built a pipeline that compiles a JSON relationship dictionary into Mermaid and SVG so diagrams regenerate when the architecture changes instead of being redrawn by hand.

Source zoneThe ARD JSON file is the only source of truth. Diagrams are never hand-edited.
Build zoneMermaid, SVG, and HTML exports come from one deterministic build, so diffs stay clean.

The pipeline parses the rendered SVG back into geometry and computes layout metrics like overlaps, density, and edge lengths, turning layout quality into regression-checkable numbers.

A test-analyze-fix loop experiments in sandboxed runs and promotes a candidate only when its metrics pass.

Measure zoneRendered SVG is parsed back into geometry, turning diagram quality into regression-checkable numbers.

Tri-agent optimization loop

The second shows the tri-agent loop that improves layout quality until it passes.

Tri-agent layout optimization
1
Testersandbox candidates
2
Analyzerranks hotspots
3
Fixerrerenders candidate
4gate
Validatemetrics pass or fail
A tester, analyzer, and fixer iterate in sandboxes. A candidate promotes only when its metrics pass; otherwise the loop repeats.

Deterministic slugs, ordering, and output paths mean generated diagrams diff cleanly and get reviewed like source.

Optimization zoneA tester, analyzer, and fixer iterate in sandboxes. A candidate promotes only when its metrics pass.

Reviewed like source

A picture worth a thousand tokens is why diagrams became a default. The compiled artifacts feed Clear Diagrams and Terragram.

Tooling & discipline

Related work

Clear Diagrams →Terragram →

Related writing

A picture is worth a thousand tokens →Dual channels and rule layers beat a longer prompt →Let the scripts judge and the agents fix →

Portfolio graph

Hover nodes · click empty canvas to zoom/pan

Maps how the work here connects. Open the Portfolio graph →

  • Professional
  • Personal
  • Skill
  • Writing