D2

D2 is a language for diagrams. You write the nodes and the edges; the layout engine decides where things go. The output is an SVG, the input is a file, and the file lives in the same repository as the thing it draws.

Why we still choose it

Because the problem with architecture diagrams has never been drawing them. It is that they are binaries — a PNG in a wiki, a .drawio somebody exported once, a Visio file that opens on one laptop. Nobody updates a binary, because updating it means opening a drawing program and moving arrows around for fifteen minutes to reflect a one-line change. So the diagram describes the system as it was on the day someone had the time.

A diagram that is text has a better failure mode: it goes stale in the same commit that changes the system, where a reviewer can see the diff. That is the entire argument, and it is the same one we make about NixOS and about pf — the value is not the syntax, it is that the description and the thing described move together.

It matters for compliance too. NIS2 Article 21(2)(a) asks for risk analysis and security policies to be written down. An assessor is not impressed by a picture; they are impressed that the picture is generated from the same repository as the estate, with a commit history behind it.

How we use it

Every handover pack contains a diagrams/ directory: the network topology, the before-and-after of a migration, and the backup paths. They are rendered in CI alongside the site build, so a diagram that no longer compiles fails the build rather than shipping wrong.

Layout is a flag. --layout=elk for anything that is mostly a flow, which is most infrastructure. TALA — the engine that was the one paid piece of D2 until it was released under MPL-2.0 in September 2026, bundled from v0.9.0 — is better on messy network pictures where its willingness to rearrange things pays off.

When it is the wrong answer

For a diagram drawn once for a pitch and thrown away, use whatever is quickest; the version-control argument does not apply to something with no second version. If a team genuinely works on diagrams together on a canvas, in real time, a canvas tool fits better and we say so.

And TALA has honest limits its own authors publish: it uses randomness, so small edits can move the layout about; it handles directed acyclic graphs worse than Dagre or ELK, which is the shape most infrastructure diagrams take; and it scales nonlinearly on large diagrams. None of that is disqualifying. It does mean picking the engine per diagram rather than per project.