C4 model

The C4 model is a discipline more than a notation: draw the same system at four zoom levels, and never mix two levels in one diagram. Most confusing architecture diagrams are confusing because they mix levels.

Capable supports both common routes: C4-PlantUML, and the Structurizr DSL where one model generates every view.

#When to reach for one

• Architecture documentation that people outside the team will read.

• Onboarding, where context comes before components.

• Any system where the current diagram tries to show everything at once.

#How to draw it in Capable

#A worked example

A system context diagram, C4 level 1:

The source, which you can paste into a new diagram and edit:

@startuml
!include <C4/C4_Context>

Person(customer, "Customer", "Buys things")
System(shop, "Online shop", "Sells things")
System_Ext(payments, "Payment provider", "Takes the money")
System_Ext(email, "Email service", "Sends receipts")

Rel(customer, shop, "Browses and orders")
Rel(shop, payments, "Charges card", "HTTPS")
Rel(shop, email, "Sends receipt", "SMTP")
@enduml

#A few things that catch people out

• Level 1 has no technology on it. If your context diagram mentions Kubernetes, it is a container diagram.

• Most teams need levels 1 and 2 only. Level 3 is for the parts that are genuinely hard.

• Structurizr keeps views consistent, at the cost of learning a DSL. Worth it above about six diagrams.

#Related

Cheap to change means it stays true.