Creating architecture diagrams with C4 and coding agents

2026-03-11T00:00:00+00:00

LLMs can draw diagrams, but you get better results with a conceptual model, a validation loop, and a lightweight verification pass against the codebase than with free-form diagramming.

I used the C4 model</a> extensively to map architecture landscapes. Last week I saw an opportunity to catch up with it and try it out with coding agents. I found that modelling architecture in a text-based format with guardrails (a DSL with rules) is easier and more consistent for a coding agent. I tried it out on a small Rust project I know well. This post is a field note of my findings.

C4</a> is a zoom-in model for software architecture.

This post discusses only the levels we actually need:

System context: people and software systems.</li>

Container: deployable/runnable things inside a software system.</li>

Component: the main building blocks inside a container.</li> </ul>
A key element for coding agents: C4 can be expressed as a text model (a DSL), so the architecture model can be edited like code and validated/exported via a CLI.
C4 is model-as-code: one model, many views/diagrams. </aside>
The test project</h2>
To try this out, I used one of my personal projects: a text-based time-tracking application</a> with two runtime modes (a CLI and a web dashboard). Both operate on the same domain and the same Markdown time-entry files.
The functionality does not matter much for this post, except for two things. First, the codebase is relatively small and easy to analyse. Second, it is well-structured: ports and adapters, plus behaviour-driven, DSL-based acceptance tests.
I've used C4 on larger landscapes too. I expect the workflow to translate, but the experience will differ on larger (or less structured) codebases.
Building the model</h2>
I started the coding agent session with a direct request to build C4 diagrams for the project at system and container level, with the DSL written first.
build me a c4 model at system level and container level (as defined by the C4 model). Please create the DSL first reference: c4model.com </code></pre>
Below, I'll go through the process using the diagrams, but keep in mind these are all generated from a text-based DSL. From the start, the agent produced a working model in the Structurizr DSL. I then gave it a command to run Structurizr CLI</a> as a check at each step.
To start with, the agent inspected the Rust codebase to work out the system boundary. It established one Time Tracker</code> software system with two runtime modes: a CLI and a web dashboard. Both use the same Markdown time-entry files.
(Apologies for the dark diagrams; dark mode was enabled when I took these screenshots. To enlarge them, open the images in a new tab.)

Here is a summary of the session:
One of the first decisions was scope: whether to model only the web path or both runtime paths. The choice was to represent them as separate containers.</li>We modelled a software system, two application containers, an internal datastore for run statistics, and the Markdown time-entry files as an external dependency. That first version was structurally correct.</li> </ul> (I had completely forgotten about the runtime statistics feature ...) After the first version, something felt missing between the Markdown files and the CLI/web containers: the shared core logic. In C4 terms, that isn't another container; it belongs at component level. So I kept the container model strict and added the component level to make the shared logic explicit. I initially asked it to model the shared core logic as a container, but the agent pushed back, and the model improved because of it. I asked it to add component views for both runtime containers instead of inventing a fake core</code> container. That preserved a strict container model while making the architecture more insightful. </li> Naming discussions helped sharpen the model. The agent came up with names I was not sure about, but on a first pass it probably did a better job than I would have. One direction I set explicitly was to name things as close as possible to the codebase. The names were not bad, but this is not where I want to leave room for interpretation. </li> To support those component views, we introduced a shared component fragment that both CLI and web could include. That shared layer covered parsing, domain types, reporting, and execution statistics. The result was a more accurate picture of how the code is actually organised. </li> </ul> Once the model structure felt right, I shifted to presentation. I asked the agent to style it so different roles were easier to distinguish: CLI and web containers, shared components, adapters, renderers, and datastores. Then I asked for rounded boxes and a more explicit person-style user element.</li> </ul> The final result: I have also made the generated static site with the diagrams</a> available as it was straightforward to do with help from the agent. You can click the small magnifying glass icons to zoom into the next level. In summary, this result took several passes: boundaries first; then the component layer; then names aligned with the code; and finally presentation. The DSL in practice</h2> One important artefact we have not discussed yet: the DSL itself. Here is the full model</a> with the diagrams defined in the Structurizr DSL. All the edits were done by the agent, including the initial creation from scratch. I reviewed, asked questions, and iterated. Before this, I typed every box and relationship by hand (scrolling up and down the file, or keeping two windows open), added tech stacks (taking care not to confuse the order of strings), and so on. Using the agent was a major documentation speed boost, and the DSL came out clean and organised the way I prefer: relationships after the element definitions, not inside them. While I see the risk of not thinking things through, being relieved of painstaking manual element/relationship editing, working with agent also gave me: Iteration close to the code</li> Meaningful discussions on abstraction levels and naming</li> A knowledgeable architecture assistant at hand</li> </ul> Why I think it worked: the model is defined in text, so the agent can edit it like code. C4 provides guardrails through a small number of nested abstraction levels, and the DSL keeps names, descriptions, and styles consistent across views. A CLI tool to validate the model closes the loop, so the agent can check its work as it goes. In addition, you can ask the LLM to review the model, in the context of the actual codebase or not. Operationalising the workflow</h2> I used Codex CLI with Codex 5.3; any other recent coding agent and model will probably work as well. </aside> Going forward, here is how I will instruct LLMs to work with C4 and keep the architecture diagrams up to date. Agent Skill</h3> First, after completing this experiment, I turned my learning into a reusable agent skill called modelling-c4-diagrams</code></a>, which I can now use from any project. AGENTS.md instructions</h3> In the project's AGENTS.md</code> I added a short reference</a> so future agents can discover the DSL files and know how to validate/export. This avoids repeating the discovery work in each new session. - **Architecture docs (C4)**: source DSL at `docs/c4/time-tracker.dsl` (shared components in `docs/c4/shared-tracking-core.dsl`); validate with `just architecture-docs-validate`; export static site with `just architecture-docs-export` </code></pre> Verification</h3> In this project, the LLM and I used the following commands to verify the output: Validate C4 Structurizr DSL: structurizr-cli validate -workspace docs/c4/time-tracker.dsl</code></li> </ul> </li> Export C4 diagrams to docs/site for inspection (and GitHub Pages publishing) structurizr-cli export -workspace docs/c4/time-tracker.dsl -format static -output docs/site</code></li> </ul> </li> View the architecture documentation open docs/site/index.html</code></li> </ul> </li> </ul> Structurizr interface to LLM</h3> I found the validation loop with the CLI to work well. If the export succeeds, the DSL is valid and the views conform to the tool's rules. That still does not tell you whether the model is accurate, or whether the diagrams communicate well. The C4 diagram review checklist</a> is a good yardstick. The LLM did not seem to require much extra instruction to create a proper model and views. I pointed it to c4model.com at the beginning of the session, and that may have been enough context. (Hard to tell what it knows or does under the hood.) The skill I created and referenced above now serves as a main interface. Conclusion</h2> The architecture model and diagrams are insightful artefacts ("pictures can say more than words"). But most of the thinking and modelling usually happens visually, while recording it often becomes a chore. This experiment showed me that LLMs can help keep a model up to date without turning it into a separate manual process. When the model is constrained (C4) and expressed as text (a DSL), you can version it like code, review it like code, and validate/export it through a CLI. Constrained text models plus validation give coding agents a better architecture-diagram workflow than free-form diagramming. Addendum: Next experiments</h2> Some follow-ups I might try if I run this workflow again. Keeping the model in sync</h3> Work with the LLM to design how to encode parts of the architecture model directly in the codebase. Use the C4 views as shared context, then define a way to keep the model in sync with the implementation. Unless you are using a very principled framework (maybe Spring in Java?), I expect this to be quite custom per project anyway. Coding agents may lower the barrier to getting started with this kind of non-obvious quality-improvement work. Verification beyond the CLI</h3> Use an MCP like Chrome DevTools to inspect exported diagrams as a second verification step. </li> One concrete use case: manual editing is often required to position boxes and, especially, dependencies. A visual inspection could double-check that no text boxes overlap and that lines do not cross boxes. </li> Coding agents could be used to evaluate the shape of the architecture outside of the code. </li> </ul> Publishing and representation</h3> Export to Mermaid (or PlantUML) for embedding in the agent's instructions, but keep the Structurizr DSL as the source of truth. Split the DSL so documentation for each container or component lives closer to the code. A better LLM interface in tooling</h3> This requires changes to Structurizr. It could provide build/run instructions for LLMs via an extensive --help</code> output, or ship a dedicated subcommand that prints LLM instructions</a> (similar to bd prime</code>).

Ground Your ADRs with a Verification Section

2024-12-11T00:00:00+00:00

Making architectural decisions is one thing, but have you ever wondered how to make them more effective? Adding a Verification section to Architecture Decision Records (ADRs) can make the difference. This simple addition bridges the gap between theory and practice, making decisions actionable and measurable.

If you're new to ADRs, check out my post on their benefits</a> first.

Common ADR Challenges</h2>
Architecture Decision Records (ADRs) are a valuable tool for capturing architectural choices. However, they can suffer from the following weaknesses:

Decisions can be made, or become, detached from implementation </li>

Intent and success criteria remain vague or unmeasurable </li> </ol>
These challenges can lead to:

Architectural decisions that exist only on paper </li>

Difficulty in assessing whether decisions are being followed </li>

Missed opportunities for feedback and improvement </li> </ul>
Introducing Verification</h2>
Adding a 'Verification' section to ADRs helps ground these decisions in reality and improve their quality. This section details how decisions will be evaluated or implemented, creating a clear path from decision to implementation.
Writing an ADR is often only the beginning, not the end. Establishing feedback loops helps to crystallise our decisions in actual implementation.
Grounding Architectural Decisions in Reality</h3>
It is a good idea to state goals in measurable and verifiable ways, and this applies equally to architecture and engineering. This is similar to writing requirements in parallel with the tests for these requirements. Or how writing code can put an analysis to the test. Each of these practices grounds our work in reality and provides feedback on our intentions.
Architecture decisions benefit from a similar grounding. Just as business analysts and developers can collaborate through behavioural tests, architects and developers can collaborate through verification criteria. More broadly, regardless of roles, the architecture function benefits from verification criteria. This creates反馈 loops that improve quality.
Importantly, verification works in both directions. Architecture and implementation connect and as such developers engage with the architecture and in return the architect receives feedback on what is working and what is not. When decisions aren't being acted upon, it becomes visible, which is a sign to investigate why and adapt.
A key benefit of keeping verification in mind: ADRs become more actionable and effective.
Verification Approaches</h2>
You might think this adds substantial work to your process. Not necessarily so. Verification methods can range from simple to sophisticated. Different architectural decisions require different verification approaches. Or you may, to get started, decide to go for a very light-weight approach.
Choose an approach that matches your context and needs. Here are some options:

Ask questions: the simplest approach uses straightforward questions for self-assessment. </li>

Automated tests / fitness functions: integrate checks in your development pipeline, look for ways to assess architectural characteristics objectively. </li>

Define metrics: what can you measure to determine if decisions are effective? </li>

Architecture Hoisting: the most comprehensive and strict approach, as described by George Fairbanks: </li> </ol>

"Architecture hoisting is a stricter kind of architecture-focused design. When following an architecture hoisting approach, developers design the architecture with the intent of guaranteeing a goal or property of the system. Guarantees are difficult to come by in any kind of software design, but architecture hoisting strives to guarantee a goal or property through architecture choices. The idea is that once a goal or property has been hoisted into the architecture, developers should not need to write additional code to achieve it." </blockquote>
Let's see some examples.
Simple</h3>
Suppose the recorded decision is to put all code in a mono-repo. Then the verification step could be as simple as:
## Verification Is your service in our mono-repo <include name>? </code></pre> This looks too easy right? In some cases it simply can be. Especially if your ADRs apply to multiple teams, and verification is not handled centrally, your verification tends to be more questions or check-based than actual steering towards an implementation. Self-Assessment</h3> For another example, suppose your cross-team decision is to adopt Continuous Delivery: ## Verification - Is the CI pipeline automated? - Can you deploy to production without manual steps? - If not, what manual gates are in place? - Are feature flags used for in-progress work? - Are branches short-lived? </code></pre> Note the self-assessment tone. This style can be adopted when architecture is an enabling and supporting function. Automated</h3> An example requiring effort but providing more guarantees to compliance: Suppose we are all working in the previously mentioned mono-repo and discover that teams are not respecting service boundaries. We decide to establish naming conventions to be able to enforce no inappropriate, accidental dependencies are created. We could again simply ask a question in the Verification section if naming conventions are followed, but automating this checking is relatively easy, so we decide to automate this check. Here we make compliance with our ADR automatic by hoisting the decision in our way of working. The verification section in the initial ADR may then look like this: ## Verification A dependency checker will be written and integrated in our build tooling for each service. - Are all of your services' build tooling integrated with the dependency checker? </code></pre> **Roles and organizational structures can heavily influence the verification section. If you have, say, a Developer Experience Team they may likely work with the teams and makes sure this gets integrated in their CI-pipeline. Other times seniors in the teams may take this upon them. Ideally these responsibilities are made clear in the Verification section as well. More examples of self-assessment questions can be found at John Lewis' Software Engineering Principles Self-Assessment</a>. Implementing the Verification section</h2> Verification</code> is my recommended term because of this definition: [!quote] "VERIFY implies the establishing of correspondence of actual facts or details with those proposed or guessed at." (Merriam-Webster) </blockquote> However, depending on your environment a different name could be a pragmatic choice. Compliance</code> often resonates better in regulated environments. I have used 'Validation' before. While regularly validating or evaluating our decisions is good practice, here we are aiming to put a system in place to check if our decisions are implemented. Here is an example of a Verification</code> section you could include in your ADR template: ## Verification How will we ensure compliance with this decision? Consider: - Questions for self-assessment - Specific metrics - Verifications in the form of tests or fitness functions - Implementation guidance - Making it easy to adopt </code></pre> Based on this, a more extended example for a Continuous Delivery ADR: ## Verification Questions: - Is the CI pipeline automated? - Can you deploy to production without manual steps? - Are feature flags used for in-progress work? Metrics: - Deployment frequency (target: daily) - Lead time for changes (target: < 1 day) - Change failure rate (target: < 15%) Implementation: - Teams must implement automated deployment, Delivery Platform Team will assist - Regular metrics reporting (data can be collected manually) </code></pre> Considerations</h2> Won't adding this section complicate writing these ADRs? Well yes, there is another section to write and you need to think about how to make your ADRs more effective. Making them more effective and actionable is something you would want regardless, so the thinking part about this should not be skipped. Instead, incorporate verification thinking while writing the ADR: state decisions in measurable and verifiable ways. Now if you ask me, is it better to have a record of a decision without this section than not having one at all? Then my answer would be yes. Don't let perfection stop you from adopting or recording your decisions - use verification to improve them over time. Conclusion</h2> Architecture benefits from being grounded in implementation. Adding a Verification section to your ADRs creates feedback loops and improves their quality. The verification section serves as more than a checklist. It: Connects architecture with implementation </li> Provides a mechanism for feedback in both directions </li> Reveals when decisions aren't being acted upon </li> Makes ADRs more actionable and effective </li> </ul> This grounding helps prevent architectural decisions from remaining theoretical or becoming shelfware.

Addendum: Next experiments</h2>
Some follow-ups I might try if I run this workflow again.</p>

Publishing and representation</h3>
Export to Mermaid (or PlantUML) for embedding in the agent's instructions, but keep the Structurizr DSL as the source of truth. Split the DSL so documentation for each container or component lives closer to the code.</p>

A better LLM interface in tooling</h3>
This requires changes to Structurizr. It could provide build/run instructions for LLMs via an extensive `--help</code> output, or ship` `a dedicated subcommand that prints LLM instructions</a> (similar to bd prime</code>).</p>`

Grounding in reality</h4>
Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4>
When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>

HanLHo. - Fractional Architect & Software Product Engineer - architecture

Notes on Why AI is the Third Coming of Domain-Driven Design

Creating architecture diagrams with C4 and coding agents

AI’s Opportunity: Pacing Control Loops with Development

On Building Reliable Software with LLMs

Ground Your ADRs with a Verification Section

Less Mentioned Benefits of Architecture Decision Records

Software Architecture Note: On Negotiation and Limiting Accidental Complexity

HanLHo. - Fractional Architect & Software Product Engineer - architecture

Notes on Why AI is the Third Coming of Domain-Driven Design

Creating architecture diagrams with C4 and coding agents

Operationalising the workflow</h2> I used Codex CLI with Codex 5.3; any other recent coding agent and model will probably work as well.</p> </aside> Going forward, here is how I will instruct LLMs to work with C4 and keep the architecture diagrams up to date.</p>

Addendum: Next experiments</h2> Some follow-ups I might try if I run this workflow again.</p>

Publishing and representation</h3> Export to Mermaid (or PlantUML) for embedding in the agent's instructions, but keep the Structurizr DSL as the source of truth. Split the DSL so documentation for each container or component lives closer to the code.</p>

A better LLM interface in tooling</h3> This requires changes to Structurizr. It could provide build/run instructions for LLMs via an extensive --help</code> output, or ship a dedicated subcommand that prints LLM instructions</a> (similar to bd prime</code>).</p>

AI’s Opportunity: Pacing Control Loops with Development

On Building Reliable Software with LLMs

Ground Your ADRs with a Verification Section

Common ADR Challenges</h2> Architecture Decision Records (ADRs) are a valuable tool for capturing architectural choices. However, they can suffer from the following weaknesses:</p> Decisions can be made, or become, detached from implementation</p> </li>

Less Mentioned Benefits of Architecture Decision Records

Objective evaluation</h4> ADRs provide a framework to evaluate design choices objectively. Instead of getting caught in personal debates, we focus on documenting and analysing technical trade-offs together.</p>

Grounding in reality</h4> Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4> When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>

Further Reading</h4> If you like to learn more about ADRs, here are some of my favorite online resources:</p>

Software Architecture Note: On Negotiation and Limiting Accidental Complexity

Addendum: Next experiments</h2>
Some follow-ups I might try if I run this workflow again.</p>

Publishing and representation</h3>
Export to Mermaid (or PlantUML) for embedding in the agent's instructions, but keep the Structurizr DSL as the source of truth. Split the DSL so documentation for each container or component lives closer to the code.</p>

A better LLM interface in tooling</h3>
This requires changes to Structurizr. It could provide build/run instructions for LLMs via an extensive `--help</code> output, or ship` `a dedicated subcommand that prints LLM instructions</a> (similar to bd prime</code>).</p>`

Grounding in reality</h4>
Through ADRs, engineering roles could become more invested in architectural decisions, while architect roles stay connected with practical implementation realities. This grounds architectural decisions in practical reality, bridging vision and practice.</p>

Preventing paralysis</h4>
When teams can't trace why and by whom past decisions were made, decision paralysis could occur. ADRs overcome this by providing the documented context teams need to more confidently evolve their systems.</p>