Diagrams as Code
A diagram with a source file can be reviewed, compared, reused and checked like code. This six-part series is the practical how: what a text source changes and which tool families fit which need, one model rendering many C4 views, a worked Archify walkthrough, architecture review in the pull request, reconciling the model with infrastructure code, inventories and traces, and letting AI agents write diagram sources under validation, inventory reconciliation and named human sign-off. It follows Mopane Medical Scheme, a fictional Gqeberha medical scheme with a three-person architecture team; its systems and figures are illustrative. Throughout, it separates what tooling proves, that a diagram is well formed, from what only evidence and review can establish: that it is true.
6 articles
- Part 1What changes when a diagram has a source fileA diagram drawn by hand is a picture. A diagram defined in text is a file that can be reviewed, compared, reused and checked. Part 1 of Diagrams as Code explains what that changes in practice, surveys the main tool families without ranking them, and says where diagrams as code is the wrong choice.10 min read
- Part 2Model once, render many viewsA drawing tool gives you pictures. A modelling tool gives you one set of elements and relationships from which every picture is selected. Part 2 explains the difference using the C4 model, shows how one model produces context, container and deployment views, and why stable element identity matters more than notation.7 min read
- Part 3Archify in practice: a claims flow from typed source to checked HTMLPart 3 of Diagrams as Code walks through one tool end to end: a Mopane claims flow written as typed JSON, the gates it must pass, the self-contained HTML it produces, and how to pin the tool in a repository. It is equally clear about what passing those gates cannot tell you.8 min read
- Part 4Architecture diagrams in the pull requestOnce a diagram has a source file, it can go through the same pull request as the code it describes. Part 4 sets out the pipeline mechanics: rendering in CI, linting the model, model diffs versus pixel diffs, and review rules with CODEOWNERS so that the right people approve architecture changes.7 min read
- Part 5Generated from reality: diagrams from IaC, inventories and tracesInfrastructure code, cloud inventories and distributed traces can all produce diagrams of what is actually running. Part 5 explains how each source works, where generated diagrams mislead, and how to reconcile discovered architecture with the intended model by identity rather than by eye.7 min read
- Part 6Letting AI agents draw the architectureAI agents can now produce architecture diagrams from a repository or a description in minutes. Part 6 of Diagrams as Code argues that a schema-first typed source is the right interface for them, and sets out the gates that catch invented components: validation, reconciliation with an independent inventory, evidence levels and a named human sign-off.7 min read
Working through any of this in your own organisation?
These articles come out of delivery work rather than theory. If the problems in this series look familiar, a short scoping conversation is usually the quickest way to work out what is worth doing first.
Talk to CloudNala