Why it matters

A C4 architecture diagram describes a software system at four levels of zoom — like Google Maps for code. The same system can be drawn as one box among its users and neighbors, or opened up to show the apps and databases inside it, or opened further to show the major pieces inside one of those apps. You pick the zoom level for the conversation you’re having, and the notation stays consistent as you move between levels. Its whole job is to replace the usual “boxes and arrows” architecture sketch — where everyone draws differently and no one agrees what a box means — with a small, leveled vocabulary that a mixed audience can actually read.

For example: a payments team is onboarding a new engineer and pulls up “the architecture diagram.” It’s a single sprawling picture with users, microservices, a database, a couple of queues, two third-party APIs, and a few class names, all on one page. The new engineer can’t tell what’s a deployable app versus an internal module versus an external dependency. Redrawn as C4, the same system becomes a stack: a Context diagram an executive could read (the payments system, its customers, Stripe and the bank), a Container diagram for the platform team (the web app, the API, the database, the queue, and the protocols between them), and one Component diagram for the area the new engineer is about to change. Each picture is sized for one conversation. The single sprawling diagram was readable to no one; the leveled set is readable to everyone, one altitude at a time.

  • What it shows. One software system at a chosen level of abstraction — the system in its environment, the apps and data stores inside it, or the components inside one of those apps — with every relationship drawn as a labeled arrow.
  • When to reach for it. You need to communicate an architecture to a mixed audience, the system is too big for one legible picture, and you want a notation engineers will actually keep up to date.
  • How to read it. Identify which level you’re looking at (the scope-and-audience label tells you), find the thing in focus, then follow the arrows — each one names a real interaction and its protocol.
  • What you’d miss without it. The coupling structure: prose lists components but rarely says which talks to which, in which direction, over what. C4 forces every connection to be drawn, and the arrows that can’t be drawn are the architectural ambiguities worth surfacing.
  • Where it misleads. It shows structure, not behavior or time — a C4 diagram won’t tell you the order of a request’s hops or how state changes; and a tidy diagram can imply the architecture is settled when the real coupling is messier than the boxes admit.

How to read it

The C4 model, created by Simon Brown, describes software architecture at four levels of zoom, and the trick to reading any C4 diagram is to first know which level you’re at. Think of it as a map with four scales. The Context level is the world map: your system is a single box in the middle, surrounded by the people who use it and the external systems it talks to — no internal detail at all, just “what is this thing, who uses it, and what does it depend on?” The Container level zooms in one notch and opens that box: now you see the separately runnable or deployable pieces — the web application, the mobile app, the API service, the database, the message queue — and the communication paths between them, each labeled with its technology and protocol. (A “container” here means a runtime unit, not specifically a Docker container.) The Component level zooms into a single container and shows the major building blocks inside it and how they relate. The Code level — classes and interfaces — is the street view, and it’s the one you almost never draw by hand; it’s generated from the code if you want it at all.

Each level is a different map scale for a different audience, and that’s the whole discipline: you don’t show all four to everyone. An executive wants the Context diagram and nothing more. A platform team lives in the Container diagram. A developer about to change one area wants the Component diagram for that area. Drawing each level as its own self-contained picture — sized for one conversation — is exactly what keeps C4 working where the ad-hoc approach fails. The common disaster is one diagram trying to show users, services, classes, and database tables at once until it’s unreadable to all of them; C4’s rule against mixing levels is the cure.

The other thing to read is the arrows. At every level, a relationship is a labeled, directional line — “Customer → Web App: places an order [HTTPS],” “API → Database: reads/writes [SQL/TCP].” The notation is deliberately small: people are stick figures, software systems and containers are rectangles carrying a name and a one-line description (and, for containers, a technology tag). Because every connection must be named, the diagram surfaces what prose hides — and a relationship nobody can label cleanly is usually a real ambiguity, an accidental coupling, or integration debt that accumulated without anyone deciding it should.

When to use it

The C4 diagram belongs to the STRUCTURE family of visual outputs — the ones that make the static, system-level shape of something visible — and within that family it is the leveled software-architecture tool: the one you reach for to communicate how a software system is built, at whatever altitude the audience needs. That places it next to several relatives, and knowing the boundaries is how you pick the right one:

  • A UML deployment diagram answers a different question: where does the software physically run — nodes, servers, and infrastructure topology. Reach for it when the conversation is about hosting and physical placement, not the logical structure C4 draws.
  • A UML sequence diagram shows interaction over time — the ordered back-and-forth of messages between parts during one scenario. C4 gives you the static skeleton; the sequence diagram animates one path through it. They’re complements, not substitutes.
  • An ad-hoc block diagram (“boxes and arrows”) is the thing C4 is meant to replace: it has no agreed meaning for a box or a level, so two of them rarely compare. C4 trades a little of that freedom for a shared, leveled vocabulary.

Reach for C4 when you need to explain a software architecture to people at different depths, the system is large enough that one picture can’t show it legibly, and you want diagrams engineers will maintain alongside the code. Skip it when the system is small enough to fit on a single honest sketch, when the audience needs the order of interactions (use a sequence diagram), or when the question is about physical deployment (use a deployment diagram). C4 is the map of how the system is structured — not how it behaves over time, and not where it runs.

How Ora builds it

Ora produces a C4 diagram from a semantic spec — a structured description that first declares the level (Context, Container, or Component) and its scope-and-audience, then lists the elements that live at that level (the people, the system in focus, the external systems, the containers, or the components) and the relationships among them, each relationship carrying a direction, a description, and where relevant a technology or protocol tag. That spec is rendered to a diagram: the source is written in Structurizr DSL or Mermaid’s C4 syntax and drawn by a backend such as PlantUML or Graphviz, with per-diagram alt-text describing the boxes, the connections, and the technology tags, and an explicit scope-and-audience label so each picture announces its altitude.

The diagram is the visual face of Ora’s system-design / architecture-description work: when you ask “lay out the architecture of this system for this audience — draw the C4,” that work identifies the right level, names the elements and their labeled relationships, and this artifact is how it shows the result. Drawing each level as its own self-contained view is the discipline that keeps the picture sized for one conversation rather than collapsing into an unreadable everything-diagram.

The technique is the work of Simon Brown, who developed the C4 model from around 2011 as a deliberately lightweight alternative to UML’s heavyweight formalism — small enough to learn in a morning, structured enough to keep diagrams comparable across teams, and zoomable enough to describe systems at the scale they actually exist. Brown’s specific critique of UML was that it offered too many notation choices and no guidance on level of abstraction, so diagrams mixed levels and lost their audience; C4’s contribution is the zoom discipline. The model is documented at its canonical site, c4model.com, and is portable across the standard documentation toolchains — Structurizr (Brown’s own tooling), Mermaid, PlantUML, and Diagrams.net — and sits in the longer lineage of architecture notation that runs through Kruchten’s 4+1 view model and the ISO/IEC/IEEE 42010 architecture-description standard.

  • Sequence Diagram — the time member: where C4 draws the static structure, a sequence diagram shows the ordered messages flowing through one path of it during a single scenario.
  • State Diagram — the lifecycle member: the states one entity moves through and the events that transition it, a behavioral complement to C4’s structural map.
  • Flowchart — the process member of the STRUCTURE-adjacent toolkit: an end-to-end path of steps and decisions, often drawn alongside a C4 set to trace a user journey through the system.
  • Concept Map — the general-purpose relative: a labeled-relationship graph for any domain of ideas, of which C4 is the specialized, leveled form for software systems.