# Container diagram

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](https://help.gocapable.com/images/att1418133529.svg)

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.

---

## Related

[Component viewC4 level 3: inside one container, for the parts that are hard.](https://help.gocapable.com/diagrams/component-view.html)

[System context diagramC4 level 1: the system, its users, and the things around it.](https://help.gocapable.com/diagrams/system-context-diagram.html)

[C4 modelBack to the C4 overview.](https://help.gocapable.com/diagrams/c4-model.html)

---

_Context first. Always._