Skip to main content

C4 Diagrams at Three Levels

What This Concept Is​

The C4 model is a hierarchy of four diagram types -- Context, Container, Component, and Code -- by Simon Brown, designed for "zooming in" on a software system. At capstone scale you draw the top three (Context, Container, Component) and never the fourth. Each diagram answers a different question for a different reader at a different zoom level:

  • System Context -- who and what interacts with the system. Users, external systems, the capstone as a single box. Audience: grader, stakeholder, you-in-week-1.
  • Container -- what are the deployable/runnable pieces. Web app, API process, database, cache, background worker. Audience: anyone deploying or reading the compose file.
  • Component -- what are the modules inside one container. The modules of the modular monolith, or the components of one service. Audience: you-in-week-5 trying to remember why scan-core and reports do not import each other.

The three diagrams are not decoration; they are a map of the system at three zoom levels. A reader who understands them understands the system. A reader who does not would struggle to modify or operate it. Each level is consistent with the next: everything on the Container diagram must appear inside a box on the Context diagram, and everything on the Component diagram must be inside a Container.

At capstone scale, the Component diagram is usually drawn for one container only -- the modular monolith process, where module boundaries matter most. Drawing a Component diagram for "Postgres" or "the SPA" is waste.

Fidelity goals: Context in under 10 boxes; Container in under 10 boxes; Component in under 12 boxes. If you exceed these, the diagram is noisy and probably wrong.

Why It Matters Here (In the Capstone)​

The capstone wins or loses on communicability. The design doc is the spine; the three C4 diagrams are its readable index. A grader asked "show me the system" points at one of the three diagrams -- and you must be able to do so without hesitation. If the diagram answers in under a minute, the system is architecturally clear. If you have to apologize for it, the architecture is probably also confused.

The diagrams also enforce the modular-monolith decision (concept 08). When you draw the Component diagram and a module imports across a boundary the diagram forbids, you caught a violation visually before the fitness function would (concept 09). The diagram is a cheap linter.

Finally, C4's three-level discipline prevents the most common capstone diagram failure mode: mixing levels. A single "architecture diagram" that shows AWS services, a web app, module names, and a Postgres table all in one frame is pseudo-information. C4 forces you to pick a level and stay at it; the reader knows what they are looking at.

Concrete Example(s) -- from a real capstone​

Example A -- inventory service, Context + Container (Mermaid form):

Component diagram for the API container:

Here the contract from the modular-monolith ADR is visible: reports does not touch scan-core except through a published API; persistence is below both; http-adapter and queue-adapter are edges, not core. A violation shows up as a diagonal arrow the diagram does not allow.

Example B -- ticketing platform, Container focus:

Note: seating is not drawn separately because for this capstone it is a module inside the API container, not a container of its own. That is an architecture decision expressed visually.

Example C -- finance aggregator, Context simplicity:

The absurd-looking dotted line to "no external systems" is deliberate: it encodes the Privacy driver visually. A grader who sees this immediately understands data does not leave the machine.

Common Confusion / Misconceptions​

  • "One big diagram is better than three." Wrong -- it mixes levels and is unreadable. The three levels are exactly the signal a reader needs.
  • "Code diagrams are the valuable ones." At capstone scale they are waste; the IDE generates them and they drift. Skip unless explicitly required.
  • "UML is C4." UML is a notation; C4 is a layering model that works with any notation (Mermaid, PlantUML, Structurizr, whiteboard photos). Pick one notation and keep it consistent.
  • "Diagrams should be auto-generated." Tempting, but a diagram is a communication artifact; auto-generated diagrams often encode incidental structure, not intentional structure. Draw by hand, then verify against reality with a fitness function.

How To Use It (In Your Capstone)​

  1. Draw Context first (10 minutes, pen + paper, then Mermaid). Capstone as one box, actors around it, external systems as boxes with dashed lines.
  2. Draw Container second (20 minutes). One box per runtime process or datastore. Not one box per module.
  3. Draw Component third for exactly one container -- the modular monolith (20 minutes). One box per module; arrows show allowed imports.
  4. Embed in design doc section 7. Not in a separate diagrams/ folder that nobody reads.
  5. Refactor the diagram when architecture changes, not the other way around. A stale diagram is worse than no diagram.
  6. Commit the Mermaid source alongside code so diff is reviewable and versioned.
  7. Pair each diagram with a 3-sentence caption: what it is, what a reader should notice, what a reader should not infer.

See also (integrative)​

The C4 model builds directly on the architecture communication discipline from S7 M01 and the architecture-from-requirements chain in S8 M01.

External references (curation-validated this session):

Check Yourself​

  1. Can you name the three levels you must draw and the one you must not?
  2. What is the maximum box count you give yourself for each level?
  3. Does every box in your Container diagram correspond to a runtime process or store (not a module)?
  4. For the Component diagram, is it clearly scoped to one container?
  5. Is each diagram captioned with three sentences: what it is, what to notice, what not to infer?

Mini Drill or Application (Capstone-scoped)​

  • Drill 1 (20 min). Sketch Context, Container, Component on paper. Check max-box counts before typing.
  • Drill 2 (25 min). Transcribe into Mermaid and commit to library/raw/design-doc.md section 7.
  • Drill 3 (10 min). Add the 3-sentence caption for each. Ask: "does this caption tell a reader what NOT to infer?"
  • Drill 4 (15 min, week 3). Hand the diagrams to a peer with zero context. Note which boxes generate questions; rename or redraw.
  • Drill 5 (10 min, week 5). Run the Component-diagram fitness function (concept 09) and verify that your import graph matches the diagram. If it doesn't, the diagram -- or the code -- is lying.

Source Backbone​

Capstone design applies earlier architecture and domain material. These books are the source backbone for the decisions in this module.