Architecture diagram examples: the C4 model and when to use each
Software architecture diagram examples using the C4 model: context, container, component, and deployment diagrams, plus diagrams as code with Mermaid.
A new engineer asks for the architecture diagram. They get three: a whiteboard photo from 2023, a slide with boxes and unlabeled arrows, and a 60-box chart that includes every Lambda function. None agree. Nobody's sure which is current.
The fix is fewer diagrams at clear levels of detail. This guide uses the C4 model, created by Simon Brown, checked on 16 November 2026.
The C4 model in one table
| Diagram | Shows | Audience | Recommended? |
|---|---|---|---|
| 1. System context | Your system, its users, and the external systems it connects to | Everyone, technical or not | Yes, for all teams |
| 2. Container | The apps, services, and data stores inside your system, and how they talk | Architects, developers, operations | Yes, for all teams |
| 3. Component | The major parts inside one container | Architects and developers | Only if it adds value |
| 4. Code | Classes or functions inside a component | Developers | Rarely; generate if needed |
Supporting diagrams: system landscape (many systems across an organization), dynamic (behavior over time for one feature), and deployment (how containers map to infrastructure).
C4 is independent of notation and tooling: boxes and labeled arrows in any tool work.
Level 1: system context
One box for your system, surrounded by the people who use it and the external systems it depends on.
flowchart LR
admin[Workspace admin] --> app[Team workspace app]
member[Member] --> app
app --> email[Email provider]
app --> pay[Payment provider]
app --> idp[Customer's identity provider]
The C4 site says this diagram is for everybody, technical and non-technical, inside and outside the team. It's the one to put in the README.
Level 2: container
What's inside your system. C4 defines a container as a runtime boundary around code that runs or data that's stored: a web app, an API, a database, a queue. It isn't necessarily a Docker container.
flowchart LR
user[Member] --> web[Web app: React]
web --> api[API: Node.js]
api --> db[(Postgres)]
api --> queue[[Job queue]]
queue --> worker[Worker: Node.js]
worker --> email[Email provider]
C4 describes this as showing the high-level shape of the architecture, how responsibilities are distributed, the major technology choices, and how containers communicate. It deliberately says little about deployment details like load balancers and replication; that's the deployment diagram's job.
Level 3: component
Inside one container: the main modules and their responsibilities. The C4 site recommends these only when they add value, and suggests automating them for long-lived documentation, since they change with the code.
Supporting diagrams
- Dynamic: how containers or components interact for one feature, in order. Use it instead of a flowchart for architecture behavior.
- Deployment: which containers run where: regions, clusters, managed services.
- System landscape: all of an organization's systems together, for large companies.
Architecture diagram vs other diagrams
| Diagram | Shows | Use for |
|---|---|---|
| Architecture (C4) | Structure: parts and connections | Understanding a system |
| Flowchart | A process: steps and decisions | A business process or algorithm |
| Data flow diagram | How data moves and transforms | Privacy reviews, data pipelines |
| Sequence or dynamic | Interactions over time | One feature's request path |
| Network diagram | Network topology | Infrastructure and security |
Diagrams as code
Diagrams drawn in a tool go stale because updating them is separate from changing the code. Text diagrams in the repository fix that:
- Mermaid renders in GitHub, GitLab, and many docs tools. The examples above are Mermaid.
- Structurizr DSL is built for C4 and generates several diagrams from one model.
Put docs/architecture.md with the context and container diagrams next to the code. Review diagram changes in pull requests.
Rules that keep diagrams useful
- A title and a key on every diagram.
- Label every arrow with what flows: "reads orders," "publishes events over HTTPS."
- Name technologies in containers: "API: Node.js."
- One level per diagram. Mixing classes and services on one canvas is where confusion starts.
- Fewer, current diagrams beat many stale ones.
What diagrams don't show
A container diagram shows that the API writes to a queue. It doesn't say why the team chose a queue over direct calls, or that it decided last month to move email to a separate service. That belongs in ADRs or a design doc, linked from the diagram.
Where Lockstep fits
Lockstep keeps the decisions behind the boxes. It captures them from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply to the code being changed, so an agent extending the worker knows why it's there.
See how it works.
Sources checked 16 November 2026
- https://c4model.com/
- https://c4model.com/diagrams/system-context
- https://c4model.com/diagrams/container
- https://c4model.com/diagrams/component
- https://c4model.com/abstractions/container
Related reading
For documenting a design in full, see the technical design document template. For engineering onboarding, see the engineering onboarding checklist. For how to lay out the code itself, see monorepo vs polyrepo.
Frequently asked questions
- What is the C4 model?
- An approach to software architecture diagrams created by Simon Brown. It uses four levels of abstraction (software systems, containers, components, and code) with a diagram for each, plus supporting diagrams for system landscape, dynamic behavior, and deployment. It's independent of notation and tooling.
- Which architecture diagrams does a team need?
- The C4 model recommends a system context diagram and a container diagram for all software teams. Component diagrams are optional and only worth creating if they add value; for long-lived docs, consider generating them automatically.
- What is a container in the C4 model?
- A runtime boundary around code being executed or data being stored, such as a web application, an API, a database, or a mobile app. It isn't the same as a Docker container, though one may be deployed as one.
- What is the difference between an architecture diagram and a flowchart?
- An architecture diagram shows structure: the parts of a system and how they connect. A flowchart shows a process: steps and decisions in order. For behavior over time in an architecture, C4 uses a dynamic diagram, similar to a sequence diagram.
- How do I keep architecture diagrams up to date?
- Keep them as text in the repository, such as Mermaid or Structurizr DSL, so changes go through pull requests. Fewer, higher-level diagrams go stale more slowly than detailed ones.
Keep reading