lockstep
4 min readNaman Jain

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

DiagramShowsAudienceRecommended?
1. System contextYour system, its users, and the external systems it connects toEveryone, technical or notYes, for all teams
2. ContainerThe apps, services, and data stores inside your system, and how they talkArchitects, developers, operationsYes, for all teams
3. ComponentThe major parts inside one containerArchitects and developersOnly if it adds value
4. CodeClasses or functions inside a componentDevelopersRarely; 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

DiagramShowsUse for
Architecture (C4)Structure: parts and connectionsUnderstanding a system
FlowchartA process: steps and decisionsA business process or algorithm
Data flow diagramHow data moves and transformsPrivacy reviews, data pipelines
Sequence or dynamicInteractions over timeOne feature's request path
Network diagramNetwork topologyInfrastructure 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

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