Diagram as code, and what the layout engine decides.
Text in, picture out. Which means the layout engine, not you, decides what it looks like.
Diagram as code means expressing a diagram in a plain-text language that a renderer turns into an image, rather than positioning shapes in an editor. Mermaid, PlantUML, D2, Graphviz and Structurizr DSL are the common examples. The benefits are all consequences of being text: it lives in the repository, it diffs in a pull request, it is versioned with the code it describes, and it can be generated by a script. The recurring limitation is that you control the structure and the renderer's layout engine controls the picture.
Reviewability is the real argument
The strongest case has nothing to do with authoring speed. A binary diagram file changes opaquely in a pull request: the reviewer sees that a file changed and has no way to see what. A text diagram produces a readable diff, so a change to the architecture is reviewed alongside the change to the code, by the same person, at the same time. That is the property that keeps a diagram accurate.
Where it frustrates people
You describe nodes and edges; the renderer decides positions. When the result is nearly right, nudging it means fighting the layout algorithm through ranking hints and invisible edges, and the workarounds are notoriously unportable between renderers. This is the honest trade: you give up direct control of the picture in exchange for a diffable source.
The languages differ more than they look
Mermaid renders natively on GitHub, which is why it spread fastest, and its layout is the weakest of the group. PlantUML covers far more diagram types and needs Java or a server. D2 was designed later with layout quality as an explicit goal. Structurizr DSL is different in kind: you describe a model once and generate several C4 views from it, rather than writing each diagram separately.
The semantic graph variant
There is a related approach that is not quite the same thing: instead of a human writing text, an agent emits a structured graph of nodes, edges and tiers with no coordinates, and a constraint solver computes the layout. It gives up the human-writable source and gains layout quality, since a solver placing boxes cannot produce an overlap. This is what Lucid Train does, which makes it adjacent to diagram-as-code rather than an instance of it.
The common languages
| Language | Renders on GitHub | Notable for |
|---|---|---|
| Mermaid | Yes, natively | Reach, weakest layout |
| PlantUML | No | Diagram type coverage |
| D2 | No | Layout quality by design |
| Graphviz | No | The layout engine others build on |
| Structurizr DSL | No | One model, many C4 views |
Questions
Related
- What Is a Sequence Diagram?Time runs down the page. That single convention is what the diagram is for.
- What Is Spec-Driven Development?Review the plan, not the pull request. The plan is a page; the pull request is a thousand lines.
- What Is a Container Diagram?The most useful diagram most teams do not have, and the worst-named one in the field.
- What Is a System Context Diagram?One box for everything you own. The value is entirely in what surrounds it.
Last updated