Producing a real C4 context-and-container diagram for a system you actually work on, getting it reviewed for accuracy, and keeping it in a shared location so it stays a living reference rather than a one-off, quickly-outdated artifact.
Published September 23, 2026
Architecture Diagramming, earlier in this platform's System Design content, covers the MECHANICS of drawing a diagram well in an interview setting. This lesson is about a related but distinct skill: producing and MAINTAINING a real architecture diagram for a system you actually work on, as ongoing documentation rather than a one-time interview exercise.
Level 1 — System Context: your system as ONE BOX, showing its relationship to
users and OTHER systems it depends on or is depended on by — the 30,000-foot view
Level 2 — Container: zooming into your system, showing its major deployable
pieces (services, databases, the frontend) and how they communicate
The C4 model (Context, Container, Component, Code — most real documentation only needs the first two levels) gives a standard vocabulary for "which level of detail am I showing." A Context diagram answers "what does this system talk to, and why" for someone with zero prior context — useful for a new team member, or an engineer from an adjacent team trying to understand how your system fits into the broader picture. A Container diagram goes one level deeper, showing YOUR system's actual internal pieces (this connects directly to Domain Decomposition and Architecture Diagramming's first-pass boxes-and-arrows principle, applied here as a genuine, lasting artifact rather than a whiteboard sketch that gets erased).
A diagram drawn from memory, by one person, without review, is reliably wrong in some detail — a service that was decommissioned six months ago still shown, a dependency that's now indirect through a different path drawn as direct, or simply an omission the author didn't think to include because it's so familiar it's invisible to them. A peer or manager review specifically checking the diagram against CURRENT reality (not just "does this look reasonable") is what turns a plausible-looking diagram into a genuinely trustworthy one — the review step is not optional polish, it's what the artifact's actual value depends on.
WRONG: a diagram embedded as an image in a one-time Slack message or an old
design doc, effectively unfindable and never updated again
RIGHT: a diagram in a shared, versioned location (a wiki page, a diagrams-as-code
file in the repo itself) that's the ACKNOWLEDGED source of truth, updated as
part of any significant architecture change
A diagram's value decays fast once it's inaccurate — and it becomes inaccurate the moment a real architecture change happens without the diagram being updated to match. The fix isn't perfection (no diagram stays perfectly current indefinitely) — it's LOCATION and OWNERSHIP: keeping it somewhere genuinely discoverable (not buried in an old doc nobody revisits) and treating updating it as a normal, expected part of any PR that changes the actual architecture it depicts, similar in spirit to how IaC changes and their actual infrastructure consequences need to be kept in sync (Infrastructure as Code Awareness's drift-detection concern, applied to documentation instead of infrastructure state).
Q: How do you prevent an architecture diagram from silently going stale, beyond just intending to update it? A: The most reliable mechanisms are PROCESS-based, not willpower-based — a diagrams-as-code approach (a text-based diagram definition committed to the same repo as the code, reviewed in the same PRs) makes staleness visible in code review the same way any other outdated code would be, versus an image file living somewhere entirely disconnected from the actual change process.
Q: Is a Container-level diagram sufficient, or does a team eventually need Component-level detail too? A: Component-level detail (the internal structure WITHIN one specific container/service) is usually only worth maintaining for genuinely complex individual services, kept as a separate, more narrowly-scoped diagram — maintaining Component-level detail for EVERY service in a system is usually more maintenance burden than the ongoing value justifies, since that level of detail changes far more frequently than the Container-level structure.
Q: What's the actual audience for a Context-level diagram, given the people ON the team already know this? A: Precisely people OUTSIDE the immediate team — a new hire, an engineer from an adjacent team trying to understand an integration point, or a lead reviewing a proposed architecture change to a NEIGHBORING system who needs to understand what yours depends on; the team's own familiarity is exactly why they tend to underestimate how valuable this artifact is for everyone else.
Q: How does this connect to Design Documents, covered next in this chapter? A: A living architecture diagram is often the CURRENT-STATE reference a design document's proposed change is drawn against — a design doc proposing a new service typically references (and, once implemented, should update) the existing Container-level diagram, making the two artifacts complementary: one captures durable current state, the other captures a specific proposed change and its reasoning.