Container diagram

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

The container diagram is the one most teams actually need. It shows the applications and data stores that make up your system, what each is built with, and how they talk to each other.

In C4, a container is something that runs: a web app, an API, a database, a queue. It is not a Docker container, though it often is one.

#When to draw one

  • The main architecture diagram for a system.

  • Onboarding engineers who will work on it.

  • Design reviews of a change that crosses containers.

#What is on the diagram

Element

Meaning

Container

An application or data store that runs independently

Technology

Written on each container: the runtime or engine

System boundary

A box around your containers

Relationship

Labelled with purpose and protocol

#A worked example

A container diagram with a queue and two data stores:

Container diagram

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

@startuml
!include <C4/C4_Container>

title Containers: Order platform

Person(customer, "Customer")

System_Boundary(orders, "Order platform") {
  Container(web, "Web application", "React, served from CDN", "Storefront and account pages")
  Container(api, "Order API", "Node.js", "Order lifecycle, pricing and payment orchestration")
  Container(worker, "Fulfilment worker", "Node.js", "Processes queued fulfilment jobs")
  ContainerDb(db, "Order database", "PostgreSQL", "Orders, items, customers")
  ContainerQueue(queue, "Job queue", "Redis Streams", "Fulfilment and notification jobs")
}

System_Ext(payments, "Payment provider")
System_Ext(warehouse, "Warehouse system")

Rel(customer, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads and writes", "SQL/TCP")
Rel(api, queue, "Enqueues jobs to")
Rel(api, payments, "Charges cards using", "HTTPS")
Rel(worker, queue, "Consumes jobs from")
Rel(worker, db, "Reads and writes", "SQL/TCP")
Rel(worker, warehouse, "Sends fulfilment to", "SFTP")
@enduml

#A few things that catch people out

  • Put the technology on every container. It is half the value of the diagram.

  • Two containers sharing a database are more coupled than the diagram suggests. Say so.

  • Keep external systems outside the boundary, drawn the same way as on the context diagram.

Context first. Always.