LLMs likes C4 Diagrams

After 25 years of drawing boxes on whiteboards, I think we are talking to AI the wrong way

I have been building software for a long time. Long enough to have watched every major shift in how developers communicate from handwritten specs to wikis, from wikis to Jira tickets, from Jira tickets to README files that nobody reads. And through all of it, one thing has never changed.

When developers need to understand something, they draw a box.

Walk into any engineering room during a sprint planning session. Walk into any architecture review. Walk into a conversation between two developers trying to debug a gnarly problem. The first thing someone does is grab a marker or open a Miro board, or pull up an Excalidraw canvas and start drawing. Not writing. Drawing.

We have always thought in diagrams. The tools change. The habit does not.

Why UML Was Right About the Problem and Wrong About the Solution

Back in the 1990s, a group of academics and engineers looked at this behaviour and said: We should standardise this. If developers are going to draw diagrams anyway, let us give them a common language so those diagrams mean the same thing to everyone.

That was UML. And in theory, it was brilliant. Class diagrams, sequence diagrams, use case diagrams, activity diagrams, deployment diagrams UML had a notation for every possible thing you might want to express about a software system. It was rigorous. It was complete. It was formally defined.

It was also completely ignored by about 90% of working developers.

Not because developers are lazy. Developers are not lazy. Developers are pragmatic. And UML was not pragmatic. It had too many diagram types. Too many rules. Too much ceremony. To use it properly, you needed to know the notation, which required time to learn. You needed tooling to draw it correctly. You needed everyone on the team to know it too.

So what actually happened was: architects used UML because that was part of the job. Senior engineers used class diagrams when they needed to explain a design pattern to someone. Everyone else drew boxes on whiteboards and called it a day.

The problem with boxes on whiteboards is that they disappear when someone wipes the board. And even when they do not disappear, they are ambiguous. What does this box represent? A service? A database? A team? A user? Without a shared vocabulary, every whiteboard diagram is a private language that only the person who drew it fully understands.

We had the right instinct diagrams, but no standard that was simple enough to actually stick.

C4 Fixed What UML Got Wrong

In 2011, Simon Brown introduced the C4 model, and something shifted.

C4 is not a complete formal notation. It is four zoom levels with a clear, minimal vocabulary. Start with the System Context, which uses the system and what external systems it connects to. Zoom in to Containers the deployable units that make up the system: apps, services, databases. Zoom in further to Components the internal structure of each container. And all the way in to Code the classes and interfaces, though in practice most teams stop at the component level.

Four levels. A handful of element types. A simple rule: each level is a zoom into the previous one.

That simplicity is why it spread. The dev teams I have worked with and talked to over the last decade adopted C4 not because their company mandated it, but because it matched how they already thought. It was not a new way of thinking. It was a standard for something they were already doing on whiteboards. You just replace “this box is… you know, the backend thing” with “this is a Container, specifically the Order Service, running on Node.js.”

The vocabulary reduced ambiguity. The hierarchy reduced scope creep. The simplicity made it accessible to the whole team, not just the architects.

And now for the first time in my career, I work with teams where the diagrams actually stay up to date. Not because they are disciplined documenters. Because the diagrams are the thinking tool, not the documentation artefact.

The Lightbulb Moment

A few months ago, I was working with Claude Code on a reasonably complex refactor. I needed to move some business logic out of a monolith and into a separate service. I sat down and wrote a prompt. A long prompt. I explained the existing architecture, described the new service, listed the dependencies, described what should stay and what should move.

And I caught myself mid-way through and thought: why am I writing an essay?

I have a C4 diagram of this system. It is right there. It shows exactly what the architecture looks like. The containers. The relationships. The data flows. Every piece of context the LLM needs to understand what I am asking is in that diagram.

But I was typing paragraphs.

After 25 years, I know that the clearest way to communicate a software system to another person, another software person, is not a paragraph. It is a diagram. You show them the diagram and they understand in 30 seconds what would take 10 minutes to explain in text.

So why was I explaining my architecture in text to an AI?

The Problem With Talking to AI in Plain English

The current model for working with AI coworkers is roughly this: you describe what you want, the LLM does its best to understand the context from your description, and then it generates something. The quality of the output depends heavily on how well you described the context.

This works. I use it every day. But it has a fundamental limitation that we have just accepted without questioning it.

Plain English descriptions of software systems are inherently imprecise. When I say “the Order Service communicates with the Payment Service to capture funds,” that sentence carries the meaning but it loses a lot of structural information. It does not tell the LLM whether this is a synchronous call or an asynchronous event. It does not tell the LLM where the Order Service sits in the hierarchy of the system. It does not tell the LLM what else the Order Service connects to, or what owns what data.

A C4 diagram expresses all of that. The element types (System, Container, Application, Store, Actor) carry meaning. The direction of the arrows carries meaning. The hierarchy carries meaning. The technology annotations carry meaning. A C4 diagram is a structured, information-dense representation of the architecture that a human can read in seconds and that a machine can parse unambiguously.

The LLM does not need you to explain the architecture in a paragraph. It needs the diagram.

It Should Go Both Ways

Here is the part of this idea that I find even more interesting than giving the LLM your diagrams to read.

The LLM should also write diagrams back.

Right now when an AI coworker makes a significant architectural change adds a new service, introduces a new database, changes a data flow it describes what it did in text. “I have added a Notification Service that subscribes to the order events from the message broker. It sends emails via SendGrid.” That is fine. But it would be far better if the LLM could update the C4 diagram to reflect that change. Show you a before and after. Make the architectural change visible, not just described.

Think about what that means for a team. Your AI coworker makes a change. The code changes. And the diagram changes. The architecture documentation stays current not because someone remembered to update it but because the tool that made the change updated it automatically.

The diagram is no longer documentation. It is a live record of what the system actually looks like. And the LLM is the entity keeping it up to date.

What We Built at uxxu.io

This idea is what drove us to build two specific features into uxxu.io that I want to explain because they are the practical expression of everything I have been talking about.

Export as Prompt. You draw your C4 diagrams in uxxu.io system context, containers, components. When you want to give your AI coworker architectural context, you export the diagrams as a structured prompt. The LLM receives not a paragraph but a hierarchical, structured description of your architecture at every C4 level. It understands the boundaries. It understands the decomposition. It knows exactly where it is working. The quality of what it produces improves because it has the right context in the right format.

MCP Integration. Through our Model Context Protocol server, the LLM can interact with uxxu.io directly. It can read existing diagrams, create new ones, update elements and relationships. This means when the LLM makes architectural changes, it can reflect those changes in the diagrams. The architecture stays visible. The diagram becomes a shared artefact between the human and the AI both parties reading it, both parties writing to it.

The vision is a development workflow where the C4 diagram is the source of truth that both humans and AI reference and maintain. You show the AI the diagram. It shows you the diagram of what it changed. The whiteboard is now collaborative and it never gets wiped.

The Whiteboard Is Still There

I started this by saying that developers have always thought in diagrams. That has been true for 25 years, and I do not expect it to change in the next 25.

The whiteboard did not go away when we got IDEs. It did not go away when we got Jira, or GitHub, or Notion, or Figma. Every time we built a better tool for writing code, the whiteboard was still there for thinking about it.

The AI coworker is the most powerful tool we have ever had for writing code. But right now it is missing something. It cannot see the whiteboard.

C4 gives us a standard. uxxu.io gives us the bridge. The LLM can speak diagram it just needs the right interface.

That is what we are building. And after 25 years of drawing boxes, I think it is about time.

If this resonates with how your team works, or if you have thoughts on how diagrams and AI should interact, I would love to hear it in the comments.

You can try uxxu.io free at uxxu.io the MCP integration and diagram export are both available today.