Software architecture guide
C4 model diagram guide.Choose the right level before drawing.
The C4 model describes software architecture through four static zoom levels—system context, container, component, and code—plus landscape, dynamic, and deployment views for broader scope, runtime behavior, and infrastructure.
- Audience before notation
- One level per view
- Labeled responsibilities
- Reality checked
Prepared by Struct contributors · Updated August 4, 2026
This real Struct project shows readable boundaries and relationships; it is an engineering architecture example, not a canonical C4 reference diagram.
What the C4 model is
A hierarchy of architecture abstractions, not a required visual style.
The model was created by Simon Brown to help software teams communicate architecture at consistent levels of detail. It is notation- and tool-independent: names, types, responsibilities, technology, relationships, scope, and audience matter more than a particular box color.
Terminology in this guide follows the official C4 model website. Simon Brown's site and examples are published under CC BY 4.0; this page provides attribution, paraphrases the official definitions, and adds an original practical workflow and review guide.
Context, containers, components, code
Use the smallest set of views that answers the real question.
The four static views form a zoom hierarchy. Do not force all four into every project, and do not mix systems, containers, components, and classes on one unexplained canvas.
System context diagram
Shows the software system in scope, the people who use it, and the external software systems that directly interact with it.
- Question: where does this system fit?
- Audience: technical and non-technical stakeholders
- Exclude: internal applications, services, and deployment nodes
Container diagram
Opens one software-system boundary to show its major applications and data stores, their responsibilities, technologies, and communication.
- Question: what runs or stores data inside?
- Audience: architects, developers, and operations
- Container means an application or data store—not automatically Docker
Component diagram
Opens one container to show its major logical components, responsibilities, dependencies, and relationships to external elements.
- Question: how is this container decomposed?
- Audience: architects and developers
- Use selectively for important or complex containers
Optional implementation detail
Treat the code diagram as an exception, not a default deliverable.
A code diagram opens one component to show classes, interfaces, functions, objects, database tables, or similar implementation elements. It changes quickly and is often better generated on demand from an IDE or source analysis.
- 04Scope one componentDo not turn a code-level diagram into an unbounded inventory of the entire repository.
- ✓Show only decision-relevant detailInclude the types, functions, tables, or interfaces needed to explain a difficult implementation or review concern.
- ↻Generate when practicalPrefer source-derived views for fast-changing code, then annotate the result with the design concern it answers.
- !Do not promote code to architecture by sizeMore classes and fields do not create a clearer architecture view; maintain the intended abstraction.
Supporting C4 views
Separate enterprise scope, runtime behavior, and deployment.
The four static zoom levels do not need to carry every concern. Add a supporting view when a different scope or dimension is the real subject.
System landscape
Map the important people and software systems across an organization, department, or portfolio without centering one system. Use it as the bridge into system-specific context views.
Dynamic diagram
Show how selected systems, containers, or components collaborate at runtime for one important story, feature, failure path, or recurring interaction. Number or sequence the interactions.
Deployment diagram
Place software-system and container instances on environment-specific deployment nodes and include relevant infrastructure such as load balancers, gateways, or managed services.
Keep names consistent
Reuse the same element identities and names across views. A supporting diagram changes the concern or scope; it should not silently redefine the system.
Practical modeling workflow
Build outward-in, then deepen only where it adds value.
Start from authoritative scope and ownership rather than drawing a familiar technology stack. Each view should state the question it answers and remain understandable without a presenter filling in missing meaning.
- 01Name the audience and decisionWrite down who will read the diagram, what they need to understand, and which system or environment is in scope.
- 02Build the canonical element inventoryRecord stable names, types, responsibilities, owners, technologies, and authoritative sources before distributing elements across views.
- 03Create system context firstShow the system boundary, people, and external systems. Confirm ownership and missing integrations before zooming in.
- 04Add the container viewShow applications and data stores, explicit responsibilities, technology choices, and labeled inter-process communication.
- 05Deepen hotspots selectivelyAdd component, dynamic, deployment, or code views for complex boundaries, critical flows, operational risk, or implementation decisions.
- 06Attach rationale and verify realityLink decisions and assumptions, then compare the model with code, infrastructure, schemas, telemetry, catalogs, and accountable owners.
C4 diagram review checklist
Make every diagram understandable on its own.
The official C4 guidance emphasizes explicit scope, element meaning, technology where applicable, directional relationships, labels, and a legend. This condensed checklist adds cross-view and evidence checks.
Title, type, scope, and audience are explicit
A reader can identify the diagram type, system or environment in scope, intended audience, and question without guessing from the shapes.
Every element explains itself
Each element has a stable name, explicit abstraction type, short responsibility, and technology where the view requires it.
Every relationship has direction and intent
Labels use an active phrase, agree with the arrow direction, and name the protocol or technology for inter-process communication where useful.
Notation and terminology are consistent
A legend explains colors, shapes, borders, arrows, and acronyms. Names and element meanings remain stable between context, container, component, and supporting views.
Abstraction levels are not mixed accidentally
Systems, containers, components, and code elements appear only where the selected view calls for them, with any deliberate exception explained.
The architecture is checked against evidence
Owners, repositories, infrastructure, schemas, service catalogs, telemetry, security boundaries, and deployment reality support the claims shown.
C4-style work in Struct
Keep the diagram editable and the decisions attached.
Struct supports the workflow without claiming to certify C4 conformance or infer architecture truth. Use the system-context starter or a blank software canvas, then preserve the result as editable project data.
Model the views
Use actors, systems, clients, services, components, data stores, frames, trust zones, deployment elements, labeled relationships, and focused software starters.
- System context, layered, and service starters
- 56 native software and UML shapes
- Manual, hierarchical, grid, radial, and tidy layout
Connect the rationale
Reference diagrams, individual elements, relationships, and other specifications from editable design documents and decision records.
- Bidirectional item references
- Visual and Markdown specifications
- Versioned collaboration and review
Review and exchange
Run deterministic checks for disconnected elements, weak labels, duplicate names, and missing ownership, then export or exchange the work without flattening the source.
- Mermaid and PlantUML import paths
- SVG, PNG, PDF, and editable project export
- Checks guide review; they do not prove correctness
C4 model questions
The practical distinctions teams ask about most.
Use the official model as the authority for C4 terminology and apply only the views that improve communication, design, review, or operations.
What are the four levels of the C4 model?+
The four static zoom levels are system context, container, component, and code. They move from the system's place in the world to applications and data stores, internal components, and optional implementation-level code detail.
What is the difference between context and container diagrams?+
A system context diagram shows one software system, its users, and directly connected external systems. A container diagram opens that system boundary to show its major applications and data stores, responsibilities, technology choices, and communication paths.
Do teams need all four C4 levels?+
No. Create only the views that answer a real stakeholder question. Context and container diagrams are often enough; component and code views should be added selectively where deeper decomposition changes design, review, risk, or onboarding decisions.
Is the C4 model the same as UML?+
No. C4 defines hierarchical software-architecture abstractions and views while remaining notation independent. UML is a modeling language with standardized diagram types and notation. C4 views can be drawn with appropriate UML elements if the scope and abstraction remain clear.
How do you keep C4 diagrams current?+
Keep stable element identities and names across views, link decisions and owners, review diagrams when code or deployment boundaries change, and validate the model against source repositories, infrastructure, service catalogs, telemetry, and accountable owners.