Container Diagram

One level inside the system boundary — the separately deployable and runnable pieces, each named with the technology it is built on.

Type Structural View Stage Design Topic C4 Model Area Architecture Communication

flowchart TB
  cust(["Customer"])
  subgraph boundary["Order Management"]
    direction TB
    web["Web Application<br/><i>Next.js</i>"]
    api["Order API<br/><i>Java / Spring Boot</i>"]
    worker["Fulfilment Worker<br/><i>Java / Spring Boot</i>"]
    db[("Order Store<br/><i>PostgreSQL</i>")]
    queue[["Order Events<br/><i>Kafka</i>"]]
    cache[("Session Cache<br/><i>Redis</i>")]
  end
  pay["Payment Gateway"]

  cust -->|"HTTPS"| web
  web -->|"JSON over HTTPS"| api
  api -->|"reads and writes"| db
  api -->|"reads and writes"| cache
  api -->|"publishes"| queue
  queue -->|"consumes"| worker
  worker -->|"reads and writes"| db
  worker -->|"HTTPS"| pay

What it is

The second level of the C4 model. A container here means a separately runnable process or data store — an application, an API, a database, a queue, a single-page app — not a Docker container, although one is frequently the other. Every box carries its technology in italics, because the whole point of this level is to record the choices someone will have to live with.

When you produce it

As soon as the technology choices are real enough to defend, and before the first sprint that assumes them. It is the diagram an architecture review board actually argues about, because it is the first one where a decision is visible and reversible at reasonable cost.

Who reads it

Engineers, who use it as the map of what they are building. Reviewers, who use it to find single points of failure and questionable coupling. Operations, who use it to work out what has to be monitored and what has to be backed up.

What good looks like

Every box names its technology, including the version family where it matters.
Every arrow names its protocol and its direction of initiation. "Reads from" and "is read by" are different diagrams.
The system boundary is explicit and everything outside it is unstyled.
Data stores are visually distinct from processes.

Common mistakes

One box per microservice in a fleet of eighty. Above about fifteen boxes this level stops working; group them and drop to a component view for the interesting one.
Leaving the technology off. Then it is a context diagram with extra boxes.
Drawing the queue as an arrow. A queue is a container with its own retention, ordering and failure behaviour, and hiding it inside a line hides every interesting question about it.