A C4 model diagram gives a software team a structured way to explain architecture without forcing every audience to read code or every implementation detail. This guide provides a reusable checklist for creating Context, Container, Component, and Code diagrams, choosing the right level for each documentation task, and keeping diagrams accurate as systems and workflows change.
Overview
The C4 model organizes a software architecture diagram into four levels of detail. Each level answers a different question:
- Context: What is the system, who uses it, and which external systems does it interact with?
- Container: What are the major deployable or executable parts of the system, and how do they communicate?
- Component: What responsibilities are grouped inside a container, and how do those parts collaborate?
- Code: How is a component implemented through classes, modules, functions, or other code-level structures?
“Container” in this model does not necessarily mean a Docker container. It can describe an application, service, web app, database, message broker, or another independently meaningful part of a system. The useful boundary is the one that helps readers understand architecture and responsibilities.
You do not need to create all four levels for every project. A context diagram and a container diagram may be enough for a product overview or design review. A component diagram can support implementation planning, while a code diagram is most useful when a particular area is difficult to understand or likely to change.
The most effective workflow is to treat each diagram as documentation with an owner, a purpose, and a maintenance path. A diagram tool for developers can help with layout and collaboration, while a diagram-as-code workflow can make diagrams easier to review alongside Markdown, source code, and other documentation. The right choice depends on how your team writes, reviews, publishes, and updates technical documents.
For a broader process, see How to Create Architecture Diagrams for PRDs, RFCs, and Design Docs.
Checklist by scenario
When introducing a system to a new audience
Start with a context diagram. Its job is orientation, not exhaustive detail.
- ☐ Name the system using language familiar to its intended audience.
- ☐ Identify the main human users, teams, or organizations that interact with it.
- ☐ Add external systems that exchange meaningful information with the system.
- ☐ Label relationships with clear verbs, such as “submits orders,” “publishes events,” or “reads identity data.”
- ☐ State the system boundary visibly so readers know what your team owns.
- ☐ Remove implementation details that do not help explain the system’s purpose.
A context diagram is often the best starting point for a PRD, onboarding page, architecture overview, or decision record. It should let a reader explain the system’s role after a short review.
When planning a new feature or system design
Use a container diagram to show the major building blocks and their communication paths.
- ☐ Give every container a name, responsibility, and technology description where that information is relevant.
- ☐ Distinguish user-facing applications, backend services, data stores, workers, and messaging infrastructure.
- ☐ Show important interfaces, protocols, or message paths without turning the diagram into an API catalog.
- ☐ Mark proposed changes separately from existing architecture when the design is still under discussion.
- ☐ Include important asynchronous paths, retries, or failure boundaries when they affect the design.
- ☐ Connect the diagram to the design decision, risk, or requirement it is meant to clarify.
For event-driven systems, a simple line between services may hide important behavior. Add topics, queues, consumers, ownership, and failure paths when those details affect reliability or operations. The guide How to Diagram Event-Driven Architecture provides a focused workflow for that scenario.
When implementing or refactoring a service
Move to a component diagram only when the container’s internal structure is relevant to the work.
- ☐ Group code by meaningful responsibility rather than by every file or class.
- ☐ Show the interfaces through which components collaborate.
- ☐ Identify dependencies that matter to the planned change.
- ☐ Highlight boundaries around domain logic, persistence, integration, and presentation where useful.
- ☐ Avoid presenting a proposed refactoring as if it already exists.
- ☐ Link the diagram to a module, package, or design document that a developer can inspect.
A component diagram should answer “where does this responsibility belong?” If readers cannot use it to locate behavior or discuss coupling, it may contain the wrong level of detail.
When documenting a difficult implementation detail
Use a code-level diagram selectively. A class diagram, sequence diagram, or focused dependency view may be more useful than a complete representation of the codebase.
- ☐ Choose one narrow question, such as object collaboration, lifecycle, or dependency direction.
- ☐ Include only structures that affect that question.
- ☐ Prefer a sequence diagram when timing and message order matter.
- ☐ Prefer a class or module view when ownership and relationships matter.
- ☐ Add a source link or file reference so the diagram can be checked against implementation.
If you are unsure which visual to use, compare the purpose of a sequence diagram, flowchart, and activity diagram in Sequence Diagram vs Flowchart vs Activity Diagram.
What to double-check
Audience and scope
Write the intended audience and question near the diagram before drawing it. An architecture overview for product stakeholders should not use the same density or vocabulary as an implementation note for service maintainers. If a single image tries to serve both groups, create a linked set of diagrams at different C4 levels instead.
Names and boundaries
Use stable, recognizable names. A label such as “Service A” may be quick during a workshop but becomes ambiguous in documentation. Prefer a name that communicates responsibility. Check whether a box represents a system, application, service, database, queue, or logical component, and use a consistent visual convention for each.
Relationships
Every important arrow should communicate more than mere connectivity. Label the interaction with its purpose, and include a protocol or data format only when it supports the reader’s question. Check arrow direction carefully, especially for asynchronous messaging, scheduled jobs, callbacks, and read-versus-write relationships.
Security and operational sensitivity
Review diagrams for secrets, internal hostnames, personal data, privileged paths, and infrastructure details that do not belong in a broadly shared document. A diagram can be accurate while still being inappropriate for a particular audience. For infrastructure conventions, see Network Diagram Symbols and Conventions.
Consistency with other documentation
Compare the diagram with the relevant README, API documentation, deployment configuration, ADRs, and runbooks. An architecture diagram should not become the only place where a critical behavior is recorded. Consider pairing diagrams with Architecture Decision Records Plus Diagrams so the reason for a boundary or dependency remains traceable.
Rendering and access
Check the exported image or rendered page at the size readers will actually see. Confirm that labels remain legible, links work, alternative text or a textual summary is available where required, and the document remains usable without access to the editing tool. If diagrams live in Markdown, GitHub, Notion, or Confluence, verify the publishing path rather than assuming an export will behave identically everywhere. See Embedding Diagrams in Markdown, Notion, Confluence, and GitHub.
Common mistakes
- Starting with code: Listing classes and packages before establishing system context makes the architecture difficult to follow. Begin with the reader’s question and move down a level only when needed.
- Using one giant diagram: A single canvas containing every service, database, queue, endpoint, and class usually serves no audience well. Split it into focused views.
- Confusing deployment with architecture: A cloud or network layout can show where components run, but it may not explain responsibilities or business relationships. Add a C4 view when the design question is about software structure.
- Leaving arrows unexplained: Unlabeled lines force readers to guess whether a relationship is a request, event, data replication path, or administrative action.
- Mixing current and proposed states: Use explicit labels such as “current,” “proposed,” or “target state.” Otherwise, reviewers may approve a design believing it already exists.
- Relying on color alone: Use labels, shapes, grouping, or line styles as well as color so the meaning survives printing, grayscale viewing, and accessibility tools.
- Publishing without ownership: An unowned diagram becomes stale when a team changes a service or integration. Record an owner and a review trigger alongside the file.
- Choosing a tool before choosing a workflow: A visual editor, an online diagram maker, and a diagram-as-code tool each support different review and publishing habits. Decide whether version control, editable collaboration, embedding, or export quality matters most before standardizing.
Use a separate review pass for clarity, accuracy, security, and ownership. The Diagram Review Checklist for Engineering Teams can serve as a companion to the C4-specific checks above.
When to revisit
Review C4 model diagrams before planning cycles, major design reviews, and documentation refreshes. You do not need to redraw every level whenever a minor implementation detail changes. Instead, match the update to the boundary that changed:
- Update the context diagram when users, external systems, ownership, or the system’s purpose changes.
- Update the container diagram when services, applications, data stores, queues, deployment responsibilities, or major communication paths change.
- Update the component diagram when responsibilities or dependencies inside a container are reorganized.
- Update the code diagram when a documented implementation detail is still used for onboarding, maintenance, or a current design decision.
When tools or workflows change, check whether the diagram still renders in the team’s documentation system, whether source files are reviewable, and whether exported formats remain useful. Teams using Markdown or docs as code should include diagram updates in the same pull request as related architecture changes where practical. Teams using a visual editor should establish a clear source-of-truth location and an owner for review.
Before your next planning or architecture session, take these five actions:
- Choose one system and write the question its diagram must answer.
- Start at the highest C4 level that can answer that question.
- Label boundaries, responsibilities, and relationships before polishing the layout.
- Review the result with someone who was not involved in creating it.
- Record the owner, source location, and next review trigger beside the published diagram.
That routine keeps an architecture diagram useful as a working part of developer documentation rather than a one-time illustration.
