methodatlas
Method guideArchitecture

C4 Model

A practical method guide: clarify prerequisites and materials, understand the complete process, and look up outputs, pitfalls, and stop criteria.

ComplexityLow
Time1-4 h
Participants1-5
FormatWorkshop + async
MaturityCanonical
Plan C4 Model
01

Prerequisite

What needs to be finished first

Complete firstClear scope

Agree the subject, boundary and decision before filling the model.

A broad or mixed scope produces a misleading model.
Complete firstAccess to relevant evidence

Bring source material and people who know the work; distinguish facts from assumptions.

Unverified interpretations become false certainty.
02

Preparation

What needs to be ready before start

Materials

Shared visual workspace, source evidence, and an agreed decision question.

People / roles

Architect or lead developer, developers, product/domain representative.

Pre-read

Collect existing data, examples, constraints and relevant stakeholder perspectives.

Time needed

60–120 min for an initial model; detail and review depend on system scope.

Setup

Name software system, boundary, audience and question the diagram must answer. Show users and neighboring software systems with named relationships. Decompose the chosen system into applications/data stores/containers and technologies. Zoom into components or code only when the audience needs that level. Check consistent scope, relationship labels, legends and diagram owner.

03

Core question

The one question this method answers

Which diagrams let each audience understand the software architecture?

04

Flow

Phases with goal, actions, output and pitfall

Communicates software architecture through context, container, component and code diagrams at useful levels of detail.

C4 views

Fictional worked example

Fictional context diagram for a practice portal: patient uses web app; practice staff use admin interface; portal queries practice management and sends confirmations through email service. Container view below: web frontend, booking API, appointment database. Label the relationship: API reads open slots and requests reservation. No component view unless it answers a concrete question.

System context

Show the system, people and neighbours with relationships.

Patient → practice portal → practice management.

Container

Show applications, services and data stores inside the boundary.

Web app → booking API → appointment database.

Component

Decompose internal components only to resolve a question.

Booking service checks availability and reservation.

Code

Use code level only when detail is useful.

No code diagram without a concrete reader need.

Supporting diagrams

Add dynamic, deployment or landscape when the communication needs it.

Deployment view for operations handover.

The example text is fictional; replace it with sourced project information.

C4 model: Diagrams

  1. 1

    Question

    Choose system, audience and question

    Goal

    Diagram brief

    Inputs for this step

    • System boundary, discussion purpose and audience

    Actions

    • Define one system-of-interest boundary and the understanding question the diagrams must answer.

    Output

    Diagram brief

    Diagram brief

    Quality check

    Can an architecture view answer the question?

    Pitfall

    One diagram tries to show overview and implementation detail. Split by audience and zoom level.

    Timing: Allow time according to scope and evidence; no universal duration.

  2. 2

    Context

    Draw system context

    Goal

    System context diagram

    Inputs for this step

    • Users, neighbouring systems and evidenced relationships

    Actions

    • Show the system as one box with people and external systems; label relationships by purpose and interaction.

    Output

    System context diagram

    System context diagram

    Quality check

    Are dependencies and system boundary clear?

    Pitfall

    Internal components appear at context level. Remove internals and explain the system of interest separately.

    Timing: Allow time according to scope and evidence; no universal duration.

  3. 3

    Containers

    Add container view

    Goal

    Container diagram

    Inputs for this step

    • Context view, deployable software and data stores

    Actions

    • Decompose the system into applications, services and data stores; name responsibility and technology when useful.

    Output

    Container diagram

    Container diagram

    Quality check

    Are containers executable or deployable units?

    Pitfall

    “Container” is mistaken for a Docker container. Explain the C4 term and name the actual software unit.

    Timing: Allow time according to scope and evidence; no universal duration.

  4. 4

    Detail

    Maintain only useful zoom levels

    Goal

    Coherent set of C4 views

    Inputs for this step

    • Open architecture question, diagram convention and owner

    Actions

    • Add component, code, dynamic or deployment diagrams only to resolve a question; label legend and ownership.

    Output

    Coherent set of C4 views

    Coherent set of C4 views

    Quality check

    Are terms, direction and detail clear to readers?

    Pitfall

    Every level is generated by habit and becomes stale. Remove views without a communication purpose.

    Timing: Allow time according to scope and evidence; no universal duration.

05

Artifact

What comes out at the end

Sketch: what the artifact looks like

C4 Model · Zoom-in von Kontext bis CodeVier Ebenen vom Systemkontext bis zur Implementierung
C4 ModelVier Architektur-Ebenen zeigen den Zoom vom Systemkontext über Container und Components bis zum optionalen Code-Level.Architektur über vier Zoomstufen erklärenJede Ebene beantwortet eine andere Frage, ohne alle Details in ein Diagramm zu pressen.ZoomZoombei BedarfC1System ContextWer nutzt welches System?PersonNutzerSystemim FokusExternNachbarC2ContainerApps, APIs und DatenstoresWeb AppUIAPIBackendDatabaseDatenWorkerJobsC3ComponentBausteine im ContainerControllerEingangServiceLogikPolicyRegelnRepositoryPersistenzAdapterIntegrationC4CodeKlassen, Module, TestsService.tsModulPolicy.tsRegelRepo.tsDatenTestsBelegeSequenzDetailpfad
Form

Communicates software architecture through context, container, component and code diagrams at useful levels of detail. Record scope, evidence, assumptions, owner and next review in the versioned artifact.

Versioning / ownership

Record scope, date, participants, source version and owner. Note changed assumptions and the reason for each revision.

Tool alternatives
  • Shared whiteboard or paper template
  • Source links, records or measurement data

c4-model-working-template.md

Prepare the decision, source evidence and next review.

C4 Model: Worksheet

Question

To be confirmed

Desired outcome

To be confirmed

Scope

Run the method Time: See catalog planning range; no universal duration.

Complete this worksheet on paper or in your own document during the work.

Preparation for this scope

Method setup

  • Materials: Shared visual workspace, source evidence, and an agreed decision question.
  • Roles: Architect or lead developer, developers, product/domain representative.
  • Advance information: Collect existing data, examples, constraints and relevant stakeholder perspectives.
  • Overall time needed: 60–120 min for an initial model; detail and review depend on system scope.
  • Setup: Name software system, boundary, audience and question the diagram must answer. Show users and neighboring software systems with named relationships. Decompose the chosen system into applications/data stores/containers and technologies. Zoom into components or code only when the audience needs that level. Check consistent scope, relationship labels, legends and diagram owner.

Prepare for the work steps

Question: Choose system, audience and question

  • System boundary, discussion purpose and audience

Context: Draw system context

  • Users, neighbouring systems and evidenced relationships

Containers: Add container view

  • Context view, deployable software and data stores

Detail: Maintain only useful zoom levels

  • Open architecture question, diagram convention and owner

C4 views

System context

Show the system, people and neighbours with relationships.

...

Container

Show applications, services and data stores inside the boundary.

...

Component

Decompose internal components only to resolve a question.

...

Code

Use code level only when detail is useful.

...

Supporting diagrams

Add dynamic, deployment or landscape when the communication needs it.

...

This blank document contains only section prompts.

C4 model: Diagrams

Question: Choose system, audience and question

Expected artifact: Diagram brief

Diagram brief

Entry:

...

  • Can an architecture view answer the question?

Context: Draw system context

Expected artifact: System context diagram

System context diagram

Entry:

...

  • Are dependencies and system boundary clear?

Containers: Add container view

Expected artifact: Container diagram

Container diagram

Entry:

...

  • Are containers executable or deployable units?

Detail: Maintain only useful zoom levels

Expected artifact: Coherent set of C4 views

Coherent set of C4 views

Entry:

...

  • Are terms, direction and detail clear to readers?

Open questions and next steps

...

Method guide: https://methodatlas.meierhoff-systems.de/en/methods/c4-model/run-sheet

06

Example output

Concrete filled scenario, fictional example

Fictional example for orientation. Counts and timings describe this case and are not universal requirements.

c4-model-beispiel.md

Concrete filled scenario, fictional example

Fictional context diagram for a practice portal: patient uses web app; practice staff use admin interface; portal queries practice management and sends confirmations through email service. Container view below: web frontend, booking API, appointment database. Label the relationship: API reads open slots and requests reservation. No component view unless it answers a concrete question.

07

Pitfalls

Recognize symptoms and steer against them

Quick overview, the full text is in the matching phase in the flow

  1. Choose system, audience and questionOne diagram tries to show overview and implementation detail.View in phase
  2. Draw system contextInternal components appear at context level.View in phase
  3. Add container view“Container” is mistaken for a Docker container.View in phase
  4. Maintain only useful zoom levelsEvery level is generated by habit and becomes stale.View in phase
08

Stop criteria

When to pause, resolve prerequisites, or choose another approach

Stop if the decision question or scope is disputed; align it first.
Stop if key inputs are unavailable; list what evidence is needed.
Stop if the group treats assumptions as observed facts.

Method after Simon Brown. Curated with 1 sources.

Sources: C4 model: Diagrams

Flow, timeboxes, and pitfalls are editorially curated practice recommendations based on the listed sources.

Where to go next?

Paper illustration of two considered options leading to a decision record with a marked status and visible consequences.
Architecture
Architecture Decision Record

Documents why a container or component boundary was drawn that way.

Context Map workspace showing the question, observations, and next decision.
Domain Modeling
Context Map

Zooms out from the system view into the business bounded contexts behind it.

View in playbookBuild Architecture DocumentationMove from scattered architecture knowledge to views, decisions, and communicable documentation.

Finished the method guide?

Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.

Go to profileMore methods