iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
An architecture diagram drawn in a slide tool or a drawing app starts going stale the day the code changes. Writing the diagram as text keeps it in the repository, where a change to a service can arrive in the same pull request as the change to its picture. Two self-hostable ways to do this for C4 diagrams are the Structurizr DSL with the Structurizr CLI, and C4-PlantUML. In a hands-on comparison published on August 15, 2026, Efrain Garay, a solutions architect, built the same context, container, and component views both ways for his Agatha file-storage system. His conclusion is conditional: use Structurizr DSL when one model has to feed several views and broken references must be caught automatically, which is typical of a company or team repository, and use C4-PlantUML when a personal project needs the quickest path to a rendered image. The timings are his own observations from one example on one machine, not a general benchmark.
What the test compared
Garay built the same three levels of the C4 model in each tool: system context, containers, and components. The subject was a file-storage system, so the example exercises realistic relationships between people, the system, and its internal parts. Both versions produced the same views, which makes the line counts and timings comparable with each other, even though they say nothing about other systems. The full write-up is at efraingaray.com.
Results as the author reported them
The table below summarises the figures and descriptions from the article. Where the article does not state a value for a row, the cell says so.
| Aspect | Structurizr DSL with CLI | C4-PlantUML |
|---|---|---|
| Files in the example | One model, with views defined against it | Three files, one per level |
| Size of the example | 66 lines | 68 lines combined |
| Where shared architecture is declared | Once, in the model | Repeated across diagrams |
| Reference validation | Catches references to nonexistent elements before the model reaches the repository (author’s description) | Not stated |
| Reported model validation time | 1.3 seconds (author’s machine, Java 21) | Not stated |
| Reported time to export all views | 1.0 second (author’s machine, Java 21) | Not stated |
| How diagrams were rendered | Through the Structurizr CLI on the author’s machine | Rendered against a public PlantUML server, with no local library installed |
| Known drift risk | Not stated as a problem in the article | Model information can drift when an element is renamed, because it is written in more than one diagram |
What the timings do and do not show
The 1.3-second validation and 1.0-second export figures come from one author, one example, and one machine running Java 21. They are useful as a sense of how quickly the CLI responds to a small model. They are not expected timings for your team, your model size, or your CI runners, and they do not measure memory use or how the tools scale to larger systems. The article also reports Docker image sizes and download times, but it describes an initial timing error caused by re-downloading an image, and those figures should be read with that correction and the VPS setup in mind.
#1 Best Overall
The two line counts are close, but that does not make the two approaches equally costly to maintain. Garay’s central distinction is duplication: C4-PlantUML repeats shared facts across diagrams, so every rename has to be carried through each file, while Structurizr declares them once and lets the views reference that single definition.
Which tool fits which situation
Personal projects: C4-PlantUML
For a personal project, Garay favours C4-PlantUML. Its rendering path requires no local installation in his test, since the files were rendered against a public PlantUML server. The cost is manual consistency: when you change a component’s name, you must update every diagram that mentions it. For a small system with few diagrams, that is a reasonable trade.
Team and company repositories: Structurizr DSL and CLI
For a repository shared by several people, Garay favours the Structurizr DSL with its CLI. The model is the single source of truth, the views are generated from it, and validation flags references to elements that do not exist. That check runs before the change reaches the repository, which is where stale diagrams usually begin. Structurizr’s own documentation supports the general rationale: it describes version control and text diffs as benefits of defining architecture as code, while noting a learning curve and the difficulty of authoring the code for non-technical collaborators. The timing claims, however, are the author’s own. Structurizr’s documentation on why “as code” explains that the model holds the content while views decide the presentation, and that validation and CI/CD integration are part of the workflow.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What Garay advises against
Garay advises against running a web server only to generate images. He puts it this way: “What I would not do in either case is stand up the web server just to generate images.” In his test the CLI was the practical path. This is his recommendation, not an official Structurizr rule, and it may not suit a setup where a team already runs a Structurizr server for other purposes.
Limits of exporting and presenting the diagrams
Structurizr’s documentation on creating with the DSL and exporting to PlantUML or Mermaid confirms that a DSL workspace can be exported to those formats, so the output can be embedded in an existing documentation workflow. It also lists trade-offs you should plan for:
- Exported diagrams are static images or markup, not interactive views.
- Interactive viewer features such as zoom and tooltips are not carried over.
- Layout cannot be changed in the export path, so if the automatic layout is poor, you must accept it or change the model.
Mermaid’s architecture diagram type, documented at mermaid.js.org, is built to show relationships among services and resources, such as those found in cloud or CI/CD deployments. It was not part of Garay’s head-to-head test, so it should be evaluated separately if you are considering it.
What to compare before you choose
- Whether one shared model is needed, or repeated diagram definitions are acceptable.
- Whether broken element references should be caught automatically.
- Setup and runtime requirements: a local CLI and Java runtime, or reliance on a public rendering server.
- Rendering and layout control, and whether static export is enough for your documentation.
- How the files fit with Git, pull requests, and CI.
- Who has to edit the diagrams. Non-technical collaborators may find text-based definitions hard to write, as Structurizr’s documentation notes.
Setup and currency notes
Tool requirements, maintenance status, and export behaviour change over time, so check the current official documentation before you copy any setup steps. Garay reports that Structurizr Lite displayed a warning recommending migration to consolidated tooling. This is his observation; it is not confirmed by a primary deprecation notice in the sources used here, so treat it as something to verify before relying on Structurizr Lite.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteThe article’s test was run against a specific set of tool versions on a specific machine in August 2026. If you are reproducing it, record the versions you use, since the timings and the rendering behaviour may differ.
Quick Recap
Sources
- Efrain Garay, “Your architecture diagram is lying: I tested both ways of writing it as code,” August 15, 2026: https://efraingaray.com/en/blog/arquitectura-como-codigo/
- Structurizr documentation, “Why ‘as code’?”: https://docs.structurizr.com/as-code
- Structurizr documentation, “Create with DSL, export to PlantUML/Mermaid”: https://docs.structurizr.com/getting-started/export-diagrams-as-code
- Mermaid documentation, “Architecture Diagrams Documentation (v11.1.0+)”: https://mermaid.js.org/syntax/architecture
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
