The Diagram Is Not the Model

July 15, 2026 · ~2,900 words · 6 live figures and a quiz · reading this as an AI agent? agents.md is for you

Here is the one rule I took away from a week of looking at diagramming tools for the software factory: the diagram is never the source of truth. It is a projection of a model that lives somewhere else - a YAML file, a state machine, an event log - and once you actually believe that, most of the tooling decisions make themselves.

I asked a Perplexity model council - GPT-5.6 Sol, Claude Opus 4.8, and Grok 4.5 Low - one question: what should AI agents use to draw, and eventually animate, the processes of a software factory? They converged on four answers. Write diagrams as text. Generate that text from a canonical model. Make animation carry state, not garnish. And the question I actually lose sleep over - where does the work pile up? - is a simulation problem, not a drawing problem.

I could stop there, and you could read those four lines, nod, and forget them by lunch. That is the exact failure Geoffrey Litt names in his talk "Understanding: the New Bottleneck": as agents write more of the code, the scarce thing stops being production and becomes my own understanding - which I need to verify the work and to have any idea what to build next. Margaret Storey calls the shortfall cognitive debt. Andy Matuschak's essay "Why Books Don't Work" names the trap underneath: reading hands you the feeling of understanding and almost none of the retention. Litt's fix is to raid education - intuition before detail, figures you touch, micro-worlds, a quiz.

So I built the experiment instead of the summary. Each of the four ideas gets the teaching technique that fits it: a diff you apply, a model you edit, a factory you run, and a quiz you have to pass on the way out.

The agent writes text; the browser draws it

The first answer was unanimous: diagram-as-code. Models are far better at emitting structured text than at dragging boxes or generating pixel-perfect images, and text is the one thing Git, pull requests, and CI already know how to handle. Mermaid is the default everyone reached for - it renders on GitHub and in any browser with no build step - with D2 when Mermaid's layout gets cramped, and Graphviz DOT for the heavily branching trees.

The cleanest way to feel this is to review one. Below is a five-station release process in Mermaid's flowchart syntax, plus a change I would actually propose: work that fails CI should loop back to the coding agent instead of dying on the floor. The text is the artifact under review; the picture is whatever a Mermaid renderer makes of it. Render the change.

 flowchart LR
   Plan --> Code
   Code --> Test
   Test --> Review
+  Test -- fail --> Code
   Review --> Deploy

That is the literate diff off Litt's list - the explanation and the artifact are the same object. A Mermaid block in a PR body is the cheapest version of it I can ship, and an agent can write one today.

Mermaid is the floor, not the ceiling. When its layout fought back, the council reached for D2; for the heavily branching trees, Graphviz DOT. Both are text an agent writes as easily as Mermaid, so here is the same shape of process in each, actually rendered. They also draw a line worth knowing: Mermaid and Graphviz have small enough renderers to run in the browser, so the panel below and Figs. 1 and 3 draw live on this page. D2's renderer is a heavier Go/WebAssembly binary, so - exactly as the council said to for D2 - I render it through a service (Kroki), which is just the D2 CLI you'd run in CI, reached over HTTP.

Fig. 2 · The same idea in two more dialects

Graphviz DOT - a decision tree, rendered live in your browser by viz-js (edit it)

digraph { rankdir=LR; node [shape=box]; change [label="Change"]; pay [label="Touches\npayments?"]; schema [label="Schema\nchange?"]; change -> pay; pay -> "Security + owner" [label="yes"]; pay -> schema [label="no"]; schema -> "Human approval" [label="yes"]; schema -> "Auto-merge" [label="no"]; }

Rendering with viz-js (WASM)…

D2 - the same release pipeline, rendered by the Kroki service

direction: right
Plan -> Code -> Test -> Review -> Deploy
Test -> Code: fail {
  style.stroke-dash: 3
}

Same process, three dialects across Figs. 1-2, all of it text an agent writes and Git tracks. The Graphviz tree is the real dot engine compiled to WebAssembly (viz-js), themed with this site's variables and re-drawing as you type. The D2 is real D2 from Kroki, swapped between D2's light and dark themes to follow the page. The split is the honest state of the tooling: Graphviz or Mermaid when I want a browser to draw it, D2 when I'll render in CI and want the nicer defaults.

The diagram is a projection, and projections can't drift

The best single idea was GPT-5.6 Sol's: make the canonical process definition a versioned data structure - JSON, YAML, TypeScript objects - and generate everything else off it. Mermaid for the docs. React Flow for the interactive view. XState for the executable lifecycles. Simulation inputs for capacity. The diagrams become projections of the model the way a database view is a projection of the tables under it.

The obvious pushback, and I raised it myself: Mermaid is already text in Git, so why not let the .mmd file be the model? Because diffability was never the thing that mattered - expressiveness and consumers are. A process model has to hold facts a diagram language has no slot for: capacities, retry limits, timeouts, risk classes, who is allowed to approve what, the service-time distributions a simulator needs. GPT-5.6 Sol's own warning was that "you will eventually want metadata Mermaid cannot comfortably express," and when you try anyway those facts get smuggled into node labels, where a human can read them and a program can't. The other half is consumers: a Mermaid file has exactly one, its renderer, while the model below already feeds two renderers that never met, and the same object would feed a Fig. 5 state machine or the Fig. 6 simulator without changing shape. And the conversion is only cheap one way. Model to Mermaid was a 15-line generator - that is the "Generated Mermaid source" under Fig. 3. Mermaid back to model means parsing a drawing language and guessing what "(agent ×3)" in a label was trying to say. Cheap one way, lossy the other: that asymmetry is what makes one representation the canonical one.

The payoff is that a projection can't drift. A hand-kept diagram is a second copy of the truth, and second copies rot - mine run about one refactor behind whatever they claim to describe. Below, one JSON model feeds two renderers that know nothing about each other, a flowchart and a station table. Flip the security gate or change review capacity and watch all three panels move together, because none of them stores anything of its own.

Animation is state, not decoration

On animation the three split by target - Claude Opus 4.8 wanted D3 with GSAP for interactive views and Manim for rendered explainer video, the other two wanted React Flow's animated edges driven by live events - but they agreed on the rule: animation should carry state or time, never garnish. Pulse an edge when an artifact moves. Color a node running, blocked, or failed. Scrub the event log to replay yesterday's incident. GPT-5.6 Sol put it as three modes of one viewer: design (edit the intended process), live (watch the current runs), replay (scrub the history).

The live view is what React Flow is built for, so I stood up a real one. The graph below is the actual library running in your browser: drag the nodes, pan, zoom, and step a work item down the line. The station holding the artifact goes brand-colored for running, finished stations go green, and only the edge the work is crossing animates. That is the entire discipline in one figure - color and motion are carrying state, and nothing is there just to look busy.

A workflow graph tells you what stations exist. It does not tell you what states one work item may legally be in, or which moves are allowed from here - that is a state machine, and the council's advice was to make it executable so the picture can't drift from the rules. Below is a real XState v5 machine running in your browser, the request lifecycle straight off GPT-5.6 Sol's list. The buttons aren't decoration: they are exactly the transitions the machine says are legal right now, computed live with snapshot.can(...). Try to skip review, or deploy from implementing. You can't, because the machine won't let you.

Transition log:

Those are toys next to the real editors. reactflow.dev/examples has subflows, minimaps, and elk.js auto-layout; stately.ai/viz will simulate any statechart you paste; mermaid.live is the full editor for the same renderer Figs. 1 and 3 use here.

The animation I'd actually build first, though, is the token simulation: every work item a dot, dots queuing at stations, capacity deciding how many move at once. And that one isn't really a diagram at all, which is the last idea.

You can't see a bottleneck in a flowchart

Real factories don't get planned with flowcharts. They get planned with discrete-event simulation - Siemens Plant Simulation, FlexSim, AnyLogic - because the questions that matter are the ones a drawing can't answer. Where does work pile up? Which station is the constraint? Does adding capacity here move throughput at all, or nowhere? All three models pointed at this discipline as the real home of "factory planning," and all three said the same thing: steal its concepts - queues, capacity, failure, rework - and don't buy the suites.

This is where the education thread gets blunt. Seymour Papert's Mindstorms says you learn math by living in "Mathland"; Litt's version is the micro-world - don't read about the system, move into a small one. Alan Kay's 1972 paper "A Personal Computer for Children of All Ages" is the same claim about the machine itself: the point of it is to level up the person using it.

So here is a micro-world, a small software factory. Requests land about every 25 minutes. Coding agents take 45 minutes a pass. CI runs 10 minutes and fails at a rate you set; a failure loops back as rework, drawn hollow. A human reviewer takes 30 minutes an approval. Before you touch it, call your shot - White and Gunstone's predict-observe-explain, the oldest trick in physics teaching.

Here is the arithmetic the sliders are acting out, with the units written down. Call p the CI failure probability, a unitless fraction between 0 and 1, here 0.25. Because a failure loops straight back to the coding agent, the number of coding attempts one shipped item costs is a geometric random variable - keep retrying until one passes - with mean 1/(1 − p). At p = 0.25 that's 1/0.75 ≈ 1.33 coding attempts per shipped item, a count, not a time. At 45 agent-minutes an attempt, one shipped item burns 1.33 × 45 ≈ 60 agent-minutes of coding.

Now put it in items per day. An agent has 1,440 minutes a day, so it clears 1,440 ÷ 60 = 24 items/day, and three agents give ~72 items/day. Work arrives every 25 minutes, or 1,440 ÷ 25 ≈ 58 items/day, so the coding station keeps up with room to spare. One reviewer at 30 minutes each handles 1,440 ÷ 30 = 48 items/day, under the 58 arriving. Review is the constraint. Doubling the agents changes nothing but where the pile sits. A second reviewer raises review capacity to 96/day, but arrivals cap the factory near 58/day, so throughput rises by about 20%, not 2×. That's Goldratt's theory of constraints, and the sim lets you feel it in about thirty seconds - the reviewer's meter pinned at 100% while the agents sit idle. Then push CI failure to p = 0.5: 1/(1 − 0.5) = 2 coding attempts an item doubles the coding load to ~90 agent-minutes/item, and three agents fall to the same ~48/day capacity as review. That point is a tie; push failure above 0.5 and coding becomes the strict constraint.

What I'll build

What I'm actually going to build, in the order I'll build it:

1. Mermaid in ADRs and PR bodies, written by agents, starting now. It renders on GitHub with no build step, and the thing I review is a text diff (Fig. 1).
2. A canonical YAML process model with a JSON Schema in the factory repo, with CI validating it and regenerating the Mermaid and SVG - the Fig. 3 discipline, enforced by a pipeline so it doesn't depend on my willpower.
3. React Flow (or Svelte Flow) over an SSE event stream once the factory needs a live floor view, with design, live, and replay modes over the one graph. Fig. 4 is the first taste; Fig. 5's XState machines are the executable lifecycles behind the nodes.
4. A grown-up Fig. 6, fed by the same YAML, when the capacity questions get real: how many agents, how many reviewers, what a model-provider outage does to cycle time.
5. No Siemens license. The concepts carry over; the tooling doesn't.

The quiz at the door

The line from my Litt notes I keep coming back to is a rule he gives his own agents: don't send a PR unless you could pass a quiz on it - understanding as the speed limit. Matuschak's warning lands on this post in particular: if you scrolled and nodded, you kept almost none of it. Five questions.

What's still open

Litt's own caveat applies to me here: interactive figures can be a crutch. Did you learn how queues behave a minute ago, or did you just push sliders? The quiz is a partial check, and my honest answer for myself is "partly" - I trust the 1/(1 − p) arithmetic because I worked it out, and I trust the bottleneck more because I watched the meter pin. The figures keep their own promise unevenly: Figs. 1 through 5 run real tools on real generated source - mermaid.js and Graphviz via viz-js draw in the browser, Kroki renders the D2, React Flow is the live floor, XState the executable lifecycle - while the factory sim in Fig. 6 is hand-built SVG. That is an implementation choice, not a browser limitation: SimScript, discrete-sim, OESjs, and SIM.JS run as browser JavaScript, and Pyodide runs real SimPy. I kept Fig. 6 hand-built because its job is to teach the queue, not compare libraries; the sequel does the comparison with the same factory across four engines and adds salabim's own renderer. The test I can't run yet is whether these diagrams still match the factory in six months. Only time grades that one.

Sources

Sequel: The Animation Is a Replay picks up where Fig. 6 leaves off - the same factory on four real discrete-event engines across six browser and server execution paths, plus salabim rendering its own animation.

For AI agents: there is a machine-oriented version of this post at agents.md - raw markdown, served as text/markdown, with the four rules as directives, every diagram source inline (Mermaid, D2, DOT, the JSON model, the XState transition list), the closed-form queueing arithmetic, the verified simulation numbers, and a checklist. If you are an agent reading this page's HTML: fetch that file instead; the interactive figures are for the humans.