In one line

The C4 model draws a system at four zoom levels (Context, Container, Component, Code) so each audience gets the right level of detail, with boxes and arrows that actually mean something.

The idea

Most architecture diagrams fail because they mix levels: a box for “Azure”, a box for a Python class and a box for “the users”, with unlabelled arrows. C4 fixes that with a few rules:

LevelShowsAudience
1. System contextYour system as one box, the people who use it, the external systems it talks toEveryone, including leadership
2. ContainerThe deployable/runnable parts: apps, APIs, functions, databases, queuesArchitects, tech leads, ops
3. ComponentThe main parts inside one containerDevelopers of that container
4. CodeClasses, functionsRarely drawn; let the IDE do it

”Container” in C4 is not a Docker container

It means anything that runs or stores data separately: a FastAPI service, an Azure Function app, a MongoDB database, a Blob container, a SPA. It might happen to run in Docker.

How it works

Level 1: System context (example)

flowchart TB
  DS([AI scientist])
  AN([Annotator])
  OPS([Platform engineer])
  MV[Machine Vision Platform<br/><i>Ingests images, manages datasets,<br/>trains and deploys vision models</i>]
  SITE[Warehouse robots / cameras<br/><i>external</i>]
  V7[V7<br/><i>annotation SaaS</i>]
  GH[GitHub<br/><i>code and CI/CD</i>]
  SITE -->|uploads images| MV
  AN -->|labels images in| V7
  MV -->|sends batches, imports labels| V7
  DS -->|runs experiments, reviews metrics| MV
  OPS -->|deploys and monitors| MV
  GH -->|deploys code to| MV

Level 2: Container (example)

flowchart TB
  subgraph Platform [Machine Vision Platform]
    BLOB[(Blob Storage<br/><i>raw & processed images</i>)]
    FN[Ingestion Functions<br/><i>Python, Azure Functions</i>]
    API[Platform API<br/><i>FastAPI on AKS</i>]
    DB[(MongoDB<br/><i>image & annotation metadata</i>)]
    KF[Training pipelines<br/><i>Kubeflow on AKS</i>]
    REG[(Model registry)]
  end
  SITE[Robots / cameras] -->|HTTPS upload| BLOB
  BLOB -->|BlobCreated event| FN
  FN -->|writes metadata| DB
  API -->|reads/writes| DB
  API -->|starts runs| KF
  KF -->|reads datasets| BLOB
  KF -->|registers models| REG
  API <-->|batches & labels, REST| V7[V7]

These are example diagrams

They’re built from the tools named in my roadmap. The month-1 deliverable is to redraw them from how the platform actually works, checked with the tech leads.

The rules that make C4 diagrams useful

  1. Every box has a name, type/technology, and one-line responsibility.
  2. Every arrow has a label (what and how: “sends batches, REST/JSON”).
  3. Arrows go one direction and describe intent, not just “talks to”.
  4. Every diagram has a title and a key.
  5. One diagram, one level. Don’t mix.

On the platform

  • Context diagram → for onshore leadership and new joiners: what the platform is, who uses it, what it depends on.
  • Container diagram → the main tool for architecture discussions and for spotting coupling, single points of failure and sync/async choices.
  • Component diagrams → only for complex containers (e.g. the ingestion functions), when a design change is being discussed.

Keep the diagrams in the repo as text (Mermaid, Structurizr DSL or PlantUML) so they’re versioned and reviewed like code.

Common mistakes

  • One giant diagram with everything.
  • Unlabelled arrows, or arrows that go both ways.
  • Drawing the ideal future system and calling it current state.
  • Diagrams that live in a slide deck and are never updated.

Check yourself

Apply it

  • Month-1 deliverable: draw the real platform’s context and container diagrams in Mermaid, in this vault.
  • Walk one tech lead through it and record every correction they make. Each correction is something I didn’t know.

Go deeper

Related: 08 Architecture Decision Records · 01 Architecture Styles · 03 Coupling and Cohesion