Creating architecture diagrams with C4 and AI

Have you ever needed to explain your codebase's architecture, whether to your manager or a new team member? This brief article explains how you can create an initial architecture diagram using a straightforward and intuitive framework (C4) and with minimal effort using tools you couldn't escape hearing about last year (AI).

Let's choose a repository 🔗

Let's consider the Streamlit application "How many mailboxes are there"? It gives you the number of mailboxes in an area of your choice, categorized in private and business categories. It could be used for flyer distributions, among other use cases. While the tool is currently limited to Switzerland, the project is very cool - I recommend reading David's LinkedIn post about it. The code is open-source and today, I finally got around looking at the repo today.

How do I create an architectural diagram? 🔗

I cloned the repo and got it running within seconds¹. Next, I wanted to understand how the code works. The codebase isn't huge, but I wanted a quick overview first through an architectural diagram. Since I like C4 and used it to explain the architecture of Topoprint, I thought it would be nice to use an LLM to generate a C4 diagram first.

So, I ran aider in the cloned repository. Aider is a AI coding assistant like GitHub Copilot or Cursor but for the terminal: it assumes you have a local git repository, and every time oyu ask it to change code, it creates a new commit. It uses a repository map as a structured overview of the relevant source directories and files for an initial context overview, and you can add source files as needed to get to the code level—you don't want to add all files, so the repo map comes in handy.

With the following five prompts, I obtained a reasonably meaningful diagram. I deliberately left the typos in here to illustrate that I'm a poor typist and that LLMs can handle it.

Prompt 0: "create a C4 diagram for the architecture in PlantUML, create a file for this"

Prompt 1: "Please try harder and use the Python code"

Prompt 2: "Include the Python files and their functionality in the arcgitecture diagram"

Prompt 3: "In the architecture.puml, ther is overture.py missing. This fetches data from overture Maps"

Prompt 4: "Also, streamlit_app.oy is missing"

The last diagram still isn't perfect yet (why did it place streamlit_app.py in the odd "Wake Up Service" container?), but it’s a great starting point to finalize the architecture on your own. You can play around with the diagram code using an online editor.

And it only took about 5 minutes to generate the fifth version of the diagram! ². You may want to check out a slightly edited version of the chat log.

The Future of AI-Assisted Documentation 🔗

While this example was generated quickly, it demonstrates the powerful potential of AI-assisted documentation and diagramming using a diagram-as-code approach. The results are promising, even if they need some refinement.

The combination of diagram-as-code with AI isn't new—companies like Mermaid Chart, Eraser AI, and larger players like Miro are already leveraging this approach. I also discovered GitDiagram, an open-source tool that automatically generates repository diagrams. While its initial output for this repo needs improvement, it shows potential.

Using an AI assistant like Aider for my own code has proven to be very useful. For streamlining the documentation process with diagrams, these tools continue to evolve—we may soon see integrated architectural diagramming capabilities built in.

Any feedback? Don't hesitate to get in touch with me!