C4 Model

Architecture diagrams fail when they mix zoom levels. The C4 model fixes this by giving you four nested views, each one a different level of detail.

Overview

Simon Brown’s C4 model is a way to talk about software architecture without ending up with a wall-sized diagram nobody can read. You produce four nested diagrams: a System Context view that shows the system and its users and external dependencies; a Container view that breaks the system into deployable units like web apps, services, and databases; a Component view that opens one container and shows its internal building blocks; and an optional Code view for the rare case where a class diagram earns its keep. Each level zooms in on a piece of the previous one, so a reader can pick the altitude that matches the conversation.

We reach for C4 when teams need to onboard newcomers, negotiate boundaries, or pitch a change to people outside the codebase. The Container view in particular tends to be the diagram that pays its keep — it captures the seams a team actually owns and makes Conway’s Law visible: when the containers don’t match the team boundaries, you can see the friction. It also pairs well with a Team API, where a team explicitly publishes the surfaces other teams interact with; the Container view becomes the picture that backs up the API.

Resources

• Simon Brown, “The C4 model for visualising software architecture” (c4model.com)
• Simon Brown, “Software Architecture for Developers” (Leanpub, 2018)
• Conway’s Law — why architecture diagrams keep redrawing your org chart
• Team API — a complementary way to publish a team’s interfaces