C4

The C4 model (Context, Container, Component, Code) is a lightweight, pragmatic approach to describing and communicating software architecture. It was created by Simon Brown to bridge the gap between high-level “boxes and lines” sketches and low-level implementation details.

1. System context diagram	2. Container diagram	3. Component diagram	4. Code diagram

Purpose

• Provide a shared vocabulary for diagrams
• Help teams reason about structure, boundaries, and responsibilities
• Enable incremental detail: start with big picture, then zoom in only where needed
• Support living documentation that matches the actual system

Core ideas

• Use 4 hierarchical views:
  • System Context: how the system fits into its environment (users, external systems)
  • Container: high-level technology building blocks (apps, services, databases, message buses, etc.) and how they communicate
  • Component: main logical components inside a container and their interactions
  • Code: lowest level, often UML or auto-generated diagrams at class/interface level when necessary
• Maintain consistency of abstractions across diagrams (same names, same responsibilities)
• Focus on people and use cases: show how software supports users and other systems
• Encourage text + diagrams: short descriptions, responsibilities, and tech choices next to each element

Benefits

• Makes architecture understandable in minutes for newcomers
• Works well with modern distributed systems and microservices
• Tool-agnostic: can be drawn on whiteboards or with diagramming tools
• Scales from conceptual overviews to detailed technical views without changing notation
• Provides essentially pre-defined starting points for models, improving standardization