C4

C4-PlantUML is PlantUML plus the C4 macro library, which gives you the right shapes and the discipline of zoom levels without learning a new tool.

It is the quickest way into C4 if you already use PlantUML, and the right choice when you want one diagram at a time rather than a whole model.

#What it is good at

• Architecture documentation aimed at a mixed audience.

• One-off diagrams where a full Structurizr model would be overkill.

• Teams already comfortable with PlantUML.

#What it draws

#A worked example

A container diagram, C4 level 2:

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

@startuml
!include <C4/C4_Container>

Person(user, "Customer")
System_Boundary(shop, "Online shop") {
  Container(web, "Web app", "React", "Serves the storefront")
  Container(api, "API", "Node.js", "Business logic")
  ContainerDb(db, "Database", "PostgreSQL", "Orders and customers")
  Container(worker, "Worker", "Node.js", "Processes async jobs")
}
System_Ext(pay, "Payment provider")

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads and writes", "SQL")
Rel(api, pay, "Charges", "HTTPS")
Rel(worker, db, "Reads and writes", "SQL")
@enduml

#A few things that catch people out

• Do not mix levels. A container diagram with people and external systems on it is a context diagram that grew.

• The include line decides which macros exist. Using Container() without the container include fails.

• Above about six diagrams, Structurizr's single model becomes easier to keep consistent.

#Related

Learn one properly. Borrow the rest when you need them.