Most architecture diagrams are made the same way. Someone opens a drawing tool, drags boxes onto a canvas, connects them with arrows and exports a picture. The picture goes into a slide, a wiki page or a design document. Six months later someone needs to change it, finds the original file on a colleague's laptop or not at all, and draws a new one.
There is nothing wrong with the picture. The problem is what happens around it. A drawn diagram is hard to review, because the only way to see a change is to compare two images by eye. It is hard to reuse, because the same system drawn in three diagrams is three separate drawings. And it cannot be checked by anything except a person who happens to notice that an arrow points to a service that was retired last year.
Our view is that the most useful architecture diagrams should have a source file: a plain-text definition of the elements and relationships, kept in version control and rendered into pictures, rather than a picture that is the only record of itself. This is not a call to abandon whiteboards or drawing tools. It is a call to treat the diagrams that people rely on as engineering artefacts, with the same habits of review and history that the code already has.
We argued in Architecture diagrams should be evidence, not artwork why a diagram should carry its support and be validated. This series is about how: the practical engineering of diagrams that are defined in text. This first part sets out what a source file changes, surveys the main tool families and marks the cases where the approach does not pay.
Mopane Medical Scheme is fictional, and its systems and figures are illustrative. Mopane is a medical scheme based in Gqeberha. It runs a member app, a claims engine, a provider network portal used by doctors and pharmacies, a member registry, and a data warehouse for reporting and actuarial work. Its architecture team is three people. At the start of this series, Mopane's diagrams live in a shared drive as exported images and a handful of drawing files, and the team spends a day before every architecture review checking which of them are still true.
A picture and a file are different things
A diagram with a source file is two things: a text definition, and one or more pictures rendered from it. The picture may look exactly like a hand-drawn one. What changes is what the team can do with it afterwards.
Review. When the claims engine gains a new dependency on a fraud-scoring service, the change to the source is a few lines. Those lines can be reviewed in a pull request alongside the code that introduced the dependency. The reviewer reads the change itself, not two full diagrams side by side. That is the mechanism behind the delta view described in What changed in the architecture? Show me the delta.
Diff and history. Version control records who changed which element, when, and in which commit. "When did the provider portal start calling the member registry directly?" becomes a search of the history rather than a debate.
Reuse. In tools that separate a model from its views, an element is defined once and appears in as many views as needed. Rename the claims engine once and every view that shows it follows. Part 2 explains why this is the single largest benefit for a team that maintains more than a handful of diagrams.
Validation. A text source can be checked by a program. Does every relationship point to an element that exists? Does every container have an owner? Are names consistent? None of these checks proves the architecture is right, which is a point we return to throughout the series, but each catches a class of mistake that a drawing tool lets through silently.
There is a fifth, quieter benefit: the source is readable by other tools. A script can list every system that holds member data. An inventory can be compared with the model. An AI agent can propose a change to the source, and that proposal can be validated before anyone looks at it. Part 6 covers that last case in detail.
What it costs
The benefits are real, and so are the costs. Text-defined diagrams give up some control over layout. Most tools place elements automatically, and the result is sometimes tidy and sometimes not. Teams used to arranging every box by hand find this frustrating at first.
There is also a learning cost. Each tool has its own syntax, and none of them is as immediate as dragging a box. For an architect who draws two diagrams a year, that cost may never be repaid.
Finally, a source file only helps if it is the place where changes are made. If people keep editing exported pictures, or keep a separate drawing "for the board", the source drifts like any other document. The discipline matters more than the tool.
The tool families
There are many tools, and they keep changing. Rather than recommend one, it is more useful to understand the families they belong to and what each is built for. The facts below were checked against each project's own documentation on 28 October 2026.
Mermaid is a JavaScript tool that turns short text definitions into diagrams: flowcharts, sequence diagrams, class, state and entity-relationship diagrams, and more. Its main strength is where it renders. GitHub renders Mermaid code blocks in Markdown directly, so a diagram can live in the same README or design note as the text that explains it. Mermaid also has a C4 diagram type, which its documentation marks as experimental, with syntax that may change.
PlantUML is a long-established text-to-diagram tool with broad coverage of UML (sequence, use case, class, activity, component, state, deployment, object and timing diagrams) plus non-UML types such as ArchiMate, Gantt charts and mind maps. It uses Graphviz for layout by default and offers alternatives that do not need it. A widely used C4 extension builds on it.
The C4 model with Structurizr DSL. C4 is a way of describing software architecture at four levels, which Part 2 covers in detail. Its site describes it as independent of notation and tooling. Structurizr DSL is a text language built on C4 in which a workspace holds a model, the elements and relationships, and separately a set of views that select from that model. That separation is what makes it a modelling tool rather than only a drawing tool.
D2 is a declarative diagram scripting language: you describe what should be shown and it produces the picture. It supports more than one layout engine (dagre by default, plus ELK and TALA), which gives some control over how dense graphs are arranged.
Graphviz is open-source graph visualisation software. Its layout programs read a simple text language, DOT, and arrange nodes and edges automatically. Many other tools emit DOT, including terraform graph, which is why Graphviz often appears in generated diagrams, a theme of Part 5.
Archify's typed JSON is a newer, agent-oriented approach. An AI agent writes a typed JSON source for one of several diagram types (architecture, workflow, sequence, data flow, lifecycle and others), and the tool validates the source and layout before writing a single self-contained HTML file. We pin it at version 3.2.0 in our own repository and use it for the interactive diagrams in this series. Part 3 walks through it in practice.
These families overlap. PlantUML and Mermaid both draw sequence diagrams. Structurizr and Archify both validate. Graphviz sits underneath several others. The distinction that matters most is not syntax but whether the tool holds a model with views or one picture per file.
Choosing by need
The decision is easier when it starts from the need rather than the tool. The table below is a starting point. It is not a ranking, and a team can reasonably use two of these for different jobs.
| If your need is... | Start with | Watch for |
|---|---|---|
| A quick diagram beside the text in a README or design note | Mermaid | Each diagram is its own file; no shared model |
| Several consistent views of the same system for different audiences | C4 with Structurizr DSL | Learning the model-and-views split; agreeing naming |
| Broad UML coverage: sequence, state, class, deployment | PlantUML | Layout varies; Graphviz dependency for some setups |
| Fine control over the layout of a dense graph | D2 or Graphviz | More time on layout tuning |
| Diagrams generated from tools that already emit DOT | Graphviz | Generated noise; see Part 5 |
| Agent-authored, interactive, validated artefacts | Archify typed JSON | Pin the version; gates prove form, not truth |
At Mopane, the team ended up with two. Developers write Mermaid sequence diagrams inside design notes for individual changes, where the diagram's job ends when the change ships. The architecture team keeps one C4 model of the scheme's systems, from which the context, container and deployment views are generated. The shared drive of exported images was archived, with each picture either rebuilt in the model or marked as historical.
Where diagrams as code is the wrong choice
Two situations call for something else.
Exploration. When a team is still working out what the system should be, a whiteboard or a drawing canvas is faster than any syntax. Ideas need to be cheap to move, delete and redraw. Writing a source file too early hardens an idea before it has been tested. Mopane's architects still sketch on a whiteboard first. Only once a design has survived a conversation does it go into the model.
One-off executive pictures. A single slide for a board meeting, designed to make one point to one audience on one day, does not need a source file. It needs to be clear. If the picture is likely to be reused, or if it makes claims about the current state that someone will rely on later, it should come from the model. If it is a one-time illustration of a strategic choice, draw it and move on.
A useful test: will anyone need to change this diagram, check it or rely on it in six months? If yes, give it a source. If no, a picture is fine.
Decide which views may leave the organisation
Architecture diagrams should be evidence, not artwork made the general case for rebuilding public diagrams from a clean source. One point applies with extra force to a medical scheme. Mopane's member and claims data includes health information, which POPIA treats as special personal information. Architecture diagrams that show where that data flows are sensitive in themselves: they reveal system names, integration points and security zones. A source file makes it easy to generate a sanitised view for an external audience, with neutral names and no environment detail, from the same model the team uses internally. It also makes it easy to leak the internal one by accident. Decide which views may leave the organisation, and keep that rule in the repository next to the model.
Starting without a programme
A team does not need to convert every diagram at once. Mopane started like this:
- Pick the one diagram that is most often wrong and most often relied on. For Mopane, that was the container view of the claims engine and its neighbours.
- Rebuild it as a source file in a folder in an existing repository, so it shares the review process the code already has.
- Agree three naming rules: what a system is called, what a container is called, and how external parties are labelled.
- Render the picture in the pipeline, not on someone's laptop.
- Retire the old image so there is only one version.
That took the team about a week of part-time work. The next five parts build on it: one model with many views, a worked tool walkthrough, review in the pull request, generation from what is actually deployed, and AI agents as authors.
Next: Part 2, Model once, render many views. All parts are on the series page.
How CloudNala can help
We help architecture teams move their most relied-on diagrams to source files: choosing a tool family for their needs, setting up a model and its first views, agreeing naming rules and wiring rendering into the pipelines they already run. We also review existing architecture documentation for claims that cannot be traced, and run short workshops for architects and engineers who want to work this way.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Request an Architecture Review or write to us at consult@cloudnala.co.za