Today's systems are far more than just an application running on a few servers with a database — they are complex ecosystems. Complexity spans many layers: integrations, code, business logic, infrastructure, and much more. The best way to understand how it all fits together is through diagrams. But if you try to pack everything into a single diagram, nobody will use it. As the saying goes: if something tries to do everything, it does nothing well (*except MacGyver's Swiss Army knife). That's where the C4 Model comes in.
As an architect, I've burned through plenty of diagrams that were outdated within a month, or where one line meant a network cable and another meant a REST API call. C4 tames this chaos by acting like Google Maps for software architecture. Instead of one enormous monster diagram, you get four levels of zoom.
Level 1: Context
The big picture — maximum zoom out. Technology, programming languages, and cloud providers don't matter here. We show our system as a single "black box" and how it interacts with users and other systems inside or outside the organization.
- For whom: Literally everyone — business stakeholders, Product Owners, new developers.
- Example: An Online Banking System. The diagram shows the customer, our banking system, and external systems such as an SMS service (e.g., Twilio) or a Mainframe handling legacy accounts.
Level 2: Containers
First step inward — we open the black box from Level 1. Important: "Container" in C4 is NOT the same as a Docker container. Here, a container is simply a standalone deployable unit or data store.
- For whom: Developers, architects, DevOps/Infra teams.
- Example: We break the Banking System into a mobile app (React Native), a browser SPA (Angular), an API Application (Java/Spring Boot), and a database (PostgreSQL). We show how these pieces communicate — e.g., via HTTPS or JSON/RPC.
Level 3: Components
Another step inward. We break a single container into smaller logical pieces — components — and show their relationships and responsibilities.
- For whom: Mainly developers and architects working inside a specific service.
- Example: Zooming into the "API Application" reveals components like a Security Component (authentication), a Mainframe Facade (legacy communication), and an Accounts Controller.
Be careful at this level. If your system changes rapidly, manually maintaining component diagrams is a recipe for frustration — they'll be stale within a week.
Level 4: Code ⚠
Maximum zoom in — class diagrams, ERD diagrams, interface relationships.
- For whom: Developers.
- Example: Showing how a specific AccountsController class implements an interface and injects a repository.
In 95% of cases, skip this level for hand-drawn diagrams. Code changes too fast for manual maintenance. Well-written unit and integration tests serve as far better Level 4 documentation — they're living, always-current records of how your smallest building blocks behave. If you genuinely need class diagrams, let your IDE generate them automatically in seconds.
Architecture-as-Code Tools for C4
Drawing C4 in typical "click-and-drag" tools like Visio or Draw.io defeats the purpose — maintaining consistency across levels is a nightmare. Architecture as Code (AaC) tools work far better.
The gold standard — created by C4 model author Simon Brown himself. You define your architecture model in code (DSL, Java, or C#) and visualizations generate automatically. Rename a system at Level 1 and the change propagates everywhere.
A trusted text-based classic. With the C4-PlantUML extension (available on GitHub), you get ready-made macros for clean, C4-compliant diagrams. Ideal for storing diagrams in the repository alongside code.
Great if you maintain documentation in Markdown (e.g., on GitHub or GitLab). Mermaid renders diagrams from text natively. Levels 1 and 2 are easy to express using standard flow or relationship diagrams.