Components and C4 diagrams

🏠The everyday picture

A city map at different zoom levels: the country (where's the city?), the city (which areas?), a neighbourhood (which buildings?), a building plan (which rooms?). Each zoom answers different questions for different people.

📘What it really is

A system is made of components, each with a clear job: a web frontend, an API, a database, a payment integration, an email service, a background job worker, a cache.
Good components: one clear responsibility; a clear interface (an API or function list); hide their insides; depend on as few others as possible.
The C4 model (by Simon Brown) draws software at four zoom levels:
Context: the system as one box, with its users and the outside systems it talks to (payment gateway, email/SMS provider, Google Calendar). For everyone, including non-technical people;
Containers: the separately running parts: the React web app, the mobile app, the Node.js API, PostgreSQL, Redis, a background worker. (Here "container" means a running unit, not necessarily Docker);
Components: the main parts inside one container: in the API, the booking module, the availability module, payments, notifications;
Code: classes and functions; usually left to the code itself.
Every box gets a name, type, technology and one-line purpose; every arrow a label ("creates booking via HTTPS/JSON").
Diagrams as code (Mermaid, Structurizr, PlantUML) live in Git next to the code and change with it.

flowchart LR
  student([Student]) -->|books sessions| web[Web app<br/>React]
  tutor([Tutor]) -->|manages availability| web
  web -->|HTTPS/JSON| api[API<br/>Node.js + TypeScript]
  api --> db[(PostgreSQL)]
  api --> pay[Payment gateway]
  api --> mail[Email/SMS provider]

🖱️Try it

Draw the C4 Context and Container diagrams for the booking platform (Mermaid in a Markdown file, or draw.io), with labelled boxes and arrows. Then draw the Component diagram for the API. Show it to someone non-technical with only the Context diagram, and check they understand what the system does.

✅Quick check

What does the C4 Container diagram show?

Show the answer

The separately running parts of the system (apps, APIs, databases, workers) and how they communicate.

Why label every arrow?

Show the answer

So readers know what flows between components and how (for example, "creates booking via HTTPS/JSON").