A software architecture diagram is supposed to answer one question fast: what does this system look like, and how do its pieces talk to each other. A diagram that answers it in January and lies by June has failed it. The tool is rarely the problem. Nobody agreed on what belongs in a system-level view versus a component-level one, so the diagram ends up saying too little or far too much.
What a software architecture diagram actually shows
A diagram and a decision record solve different problems. Recording why a service boundary or a database choice got made belongs in an architecture decision record, not on a diagram. A diagram's job is narrower: show the current shape of a system to someone who wasn't in the room when it was built, a new engineer or a due-diligence reviewer.
That narrower job has a common failure mode. A diagram with forty boxes crammed onto one page tells a new hire nothing, because it doesn't say which ones matter for the question they're asking. A diagram with one box labeled "backend" tells them even less. Picking the right level of detail for the question at hand is what the C4 model is built for.
The C4 model's four levels, and what belongs at each
Simon Brown's C4 model describes itself as "an easy to learn, developer friendly approach to software architecture diagramming," built around four levels: software systems, containers, components, and code. Each level answers a different question, and most teams stop well before the fourth one.
System context: the one diagram every non-engineer stakeholder should be able to read
The system context level treats the whole system as a single box and draws everything around it: the people who use it, and the other systems it talks to. It answers the broadest question there is, what is this thing and what does it touch, and a product manager or an investor should read it without needing any code knowledge.
Container: where most teams should stop
A container, in C4's vocabulary, is anything that has to be running for the system to work: an API, a web app, a database, a queue. The container diagram breaks the single box from the system context view into those pieces and draws the connections between them. C4model.com's guidance is direct: "the system context and container diagrams are sufficient for most software development teams". Most of what a reviewer needs, how a request reaches a database and back, lives here.
The container boundary is also where access decisions tend to get made. How a repository gets split along those same boundaries is a separate decision, but a five-box diagram and a repository with one owner per box usually describe the same boundary.
Component and code: when the extra detail earns its keep
Component diagrams zoom inside a single container and show its modules. Code diagrams go a level further, down to class structure. The same c4model.com page is direct about when to stop: "you don't need to use all 4 levels of diagram; only those that add value." Draw a component diagram for the one container an engineer is about to work in, and skip the code level otherwise.
Deployment, sequence, and data-flow diagrams: beyond C4's core four
C4's four core levels describe structure at rest, not where anything runs, how a request moves through the system over time, or where data enters and leaves. The same c4model.com diagrams page names deployment and dynamic diagrams as supplementary types, alongside the core four, though it doesn't develop either as fully. Data-flow diagrams aren't part of C4 at all. Together, the three tend to fill the rest of that gap.
Deployment diagrams: where the containers actually run
A deployment diagram maps containers onto infrastructure: which service runs on which node, cluster, or region. It answers a question the container diagram never touches: if this data center goes down, what stops working. A team running everything in one cloud region can often skip it until the day someone asks about failover.
Sequence diagrams: how a single request moves through the system over time
A sequence diagram picks one request, a login or a checkout, and draws it as a timeline: which container gets called first, what it calls next, what comes back. Where a container diagram shows every possible connection at once, a sequence diagram shows one path through them in order. It answers "walk me through what happens when a user clicks this button," which a container diagram can't do alone.
Data-flow diagrams: where data enters, transforms, and leaves
A data-flow diagram tracks a different thing than calls between services: where a piece of data comes from, what transforms it along the way, and where it ends up. It matters most for anything touching personal or payment data, where a reviewer needs to trace one field, an email address, a card number, from the form it was entered on to every place it's stored or forwarded.
Diagrams-as-code vs whiteboard tools
Miro, Mural, Lucidchart, and draw.io all work the same way: someone opens a canvas and drags boxes onto it. Structurizr takes the opposite approach, describing itself as "a 'models as code' tool designed for the C4 model," where a team can "write Structurizr DSL to create multiple software architecture diagrams from a single model." Mermaid and PlantUML follow the same principle: text in, diagram out.
The drawing experience matters less than what happens six months later. Any diagram stored outside version control, whether it started life in a whiteboard tool like the ones above or somewhere else entirely, carries the same risk: nothing forces an update when the architecture changes, and the file sits wherever it was saved instead of where the code lives. A diagram generated from text lives in the repository, gets reviewed in the same pull request as the change that made it stale, and shows up as a diff instead of a screenshot nobody rechecks.
None of this means C4 requires Structurizr. C4model.com is explicit that the model is "Notation independent" and "Tooling independent," and Structurizr calls itself "the original tool for the C4 model" and "the reference implementation," not the only one. A team already using Mermaid or PlantUML loses nothing by staying there, as long as the diagrams get versioned with the code.
How a reviewer reads a diagram during due diligence or onboarding
A reviewer, whether that's a technical due-diligence consultant or a new engineer's first-week buddy, checks three things when reading a diagram, and polish isn't one of them: does it match what the code does, is it current, and does it explain the specific boundary they're worried about.
What a due-diligence review actually checks in a system's architecture comes down to whether the design holds up under more load than it sees today, and where the bottlenecks sit. A diagram with no sense of what's stateful, what scales horizontally, and what's a single point of failure doesn't answer that, however current it is.
Currency matters as much as content. A container diagram that still shows a service decommissioned eight months ago tells a reviewer the documentation isn't trusted internally either. The fix is the one that keeps a decision record honest: update the diagram when the boundaries change, in the same pull request, not on a calendar reminder nobody honors.
Who signs off on that update is worth naming too. review authority on a blended team gives a senior augmented engineer the same voting weight as any in-house senior on architecture discussions, with one exception: a decision with a lifespan longer than a typical engagement still needs an in-house senior's sign-off alongside it, since the augmented engineer won't be the one answering for it eighteen months out.
Frequently asked questions
Do you need all four C4 diagram levels?
No. C4model.com's own guidance is that most teams get what they need from system context and container, adding component or code diagrams only where the detail earns its keep. Drawing all four for every container produces more diagrams than anyone maintains.
What's the difference between a deployment diagram and a container diagram?
A container diagram shows the pieces of a system and how they talk to each other, as if the system existed in the abstract. A deployment diagram maps those same containers onto actual infrastructure: which node, cluster, or region each one runs on. A clean container diagram can still hide a single point of failure that only shows up once someone asks where things run.
Should you draw architecture diagrams as code or use a whiteboard tool?
Diagrams-as-code tools like Structurizr, Mermaid, or PlantUML fit a team that wants the diagram reviewed like code: versioned and diffed in the same pull request as the change it describes. A whiteboard tool like Miro or Lucidchart is faster for a one-off sketch, but nothing enforces an update once the meeting ends.
How often should an architecture diagram be updated?
Tie it to events rather than the calendar: whenever a container gets added, removed, or its boundary changes, and before any due-diligence review or a new hire's first week. A diagram touched only during an annual documentation sprint has no trigger to stay current between sprints.