The C4 Model: Stop Drawing One Diagram to Answer Four Different Questions
Most bad architecture diagrams aren't wrong, exactly — they're just answering four different questions on one page, for four different audiences, at once. An executive wants to know what the system does and what it talks to. A new engineer wants to know what the major pieces are. Someone debugging a specific service wants to know its internal components. Someone reading a pull request wants to see the actual code structure. Simon Brown's C4 model doesn't try to cram all four into one diagram — it says draw four, each zoomed to a different level, and stop apologizing for the fact that "the architecture diagram" was never one thing to begin with.
Four levels, one system
Context is the zoomed-out view: your system as a single box, sitting in its world alongside the users and external systems it talks to — an LLM provider, a CRM, a human. No internals, no technology choices, just "what is this thing and what does it touch." This is the diagram you show a stakeholder who's never seen the system before, and it should be legible to them in about ten seconds. Container opens that single box up into its actual deployable units — a web app, an API, a vector database, an orchestration service — each one something you could independently build, deploy, and scale. This is the level most people mean when they say "architecture diagram," and it's the one I reach for most often in design reviews. Component zooms into one container and shows its internal structure — the major groupings of functionality inside it, like a planner, a tool router, a memory store inside an orchestration service — without dropping all the way to individual classes. Code is the level most teams shouldn't hand-draw at all — UML class diagrams, generated from the actual source, showing the real classes and functions inside one component, useful occasionally but stale within a week if maintained by hand.
The rule that makes this actually work
The discipline C4 imposes is simple to state and constantly violated in practice: each diagram shows exactly one level of zoom, and you don't mix them. The failure mode I see constantly is a single diagram that shows the overall system as boxes, then suddenly drops into class names for one specific service because that's the part someone cared about most when they drew it. That diagram is now useless to three of its four possible audiences — the executive is lost in class names, and the engineer debugging that one service doesn't have enough detail to actually help them. Split it into the right number of C4 levels and each one does its actual job.
This is the same discipline I've argued for in reference architectures and in the Technical Debt Quadrant: mixing concerns that should be separated makes every downstream conversation harder, because nobody can tell which question a given artifact is trying to answer.
Why this is unusually necessary for AI systems specifically
AI systems have an extra reason to keep these levels separate that most traditional software doesn't: the Container and Component levels change at genuinely different rates, and conflating them makes both look more volatile than they are. Your Container-level shape — web app, API, vector store, orchestrator — is often fairly stable once you've settled on it. What changes constantly is what's inside the orchestrator: which agent framework, which tool-routing logic, which memory strategy, updated as the field's best practices shift underneath you, the way I described in the Stanford AI Index piece. If your only diagram mixes container-level and component-level detail, every internal refactor of the orchestrator forces you to redraw and reapprove "the architecture diagram," when really only the Component-level view changed. Keeping the levels separate means the Context and Container diagrams — the ones stakeholders actually reference in planning conversations — stay stable and trustworthy even while the Component-level internals evolve every few weeks, which is exactly the cadence AI systems actually run at right now.
The diagram you should actually maintain
In practice I keep Context and Container diagrams current in the repo, treated as documentation with the same review discipline as code, because they change rarely and stakeholders rely on them being accurate. I draw Component diagrams on demand, for specific containers, when onboarding someone or planning a change inside that container — not maintained continuously, because as I said, they go stale fast. I essentially never hand-draw Code-level diagrams; if a class relationship is that important, it belongs in a generated diagram or, more often, in the code itself being clear enough not to need one. Four levels, four different maintenance disciplines, four different audiences — and the fact that C4 makes you decide which one you're drawing before you start is most of the value.