D2

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

Why we still choose it

Drawing architecture diagrams was never the hard part. The trouble is that they are usually binaries: a PNG in a wiki, a .drawio somebody exported once, a Visio file that opens on one laptop. Nobody updates them, because a one-line change to the system means opening a drawing program and moving arrows around for fifteen minutes. So the diagram ends up describing the system as it was on the last day someone had time.

When a diagram is text, it changes in the same commit as the system, and a reviewer can see the diff. We make the same argument for NixOS and pf: what matters is that the description and the thing described move together, more than the syntax.

This helps with compliance as well. NIS2 Article 21(2)(a) asks for risk analysis and security policies to be written down. An assessor cares less about the picture than about the fact that it 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 with the network topology, the before-and-after of a migration, and the backup paths. CI renders them alongside the site build, so a diagram that no longer compiles fails the build instead of shipping wrong.

The layout engine is chosen with a flag. We use --layout=elk for anything that is mostly a flow, which covers most infrastructure. TALA was the one paid part of D2 until it was released under MPL-2.0 in September 2026 and bundled from v0.9.0. It does better on messy network pictures, where its willingness to rearrange things helps.

When it is the wrong answer

For a diagram drawn once for a pitch and then thrown away, use whatever is quickest. Version control does nothing for something that will never have a second version. If a team works on diagrams together on a canvas in real time, a canvas tool fits better and we will tell them so.

TALA also has limits that 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, and that is the shape most infrastructure diagrams take. It also scales nonlinearly on large diagrams. None of this rules it out, but it does mean we pick the engine per diagram rather than per project.