Source
Official website of C4 Model
Key principles, diagram levels, notation and examples from Simon Brown.
C4 Model — a developer-friendly approach, where the architecture is broken down into levels of abstraction. The main idea: to show the system at the right level of approximation for a specific audience, and not to explain everything with one overloaded diagram.
4 levels C4
System Context
One system surrounded by people and external systems.
Audience: Technical and non-technical audiences.
Recommendation for use: Yes, almost always.
Container
Applications and storage within the system (web app, API, DB, queue, etc).
Audience: Architects, developers, ops/support.
Recommendation for use: Yes, a basic level for teams.
Component
Components inside the selected container.
Audience: Architects and developers.
Recommendation for use: Optional if it really adds value.
Code
Code elements of a specific component (classes/interfaces/tables).
Audience: Developers.
Recommendation for use: Probably not; It's better to generate from tooling on request.
Examples of C4 diagrams
Examples in the format from the UML chapter: select a diagram type and see the corresponding visualization.
Context Example
User, external systems and one target platform on L1.
Details
Diagrams
Recommendations for core and supporting diagrams.
Supporting charts
System Landscape
Map of systems at the organization/domain level.
Dynamic
Scenario of interactions over time for a specific use case.
Deployment
Placement of containers and systems by environment (prod/stage/dev).
Notation
Notation Guidelines
Practical rules for describing elements and connections.
Notation checklist
Naming
Each element has a name and a short description.
Technologies
For containers and components, the technology is explicitly specified.
Connections
Directed connections, with a signature and clear intent.
Protocol
For inter-container communications, explicitly specify the protocol/technology.
Legend
Add legend/key to make the notation self-documenting.
Tool-agnostic
C4 is not tied to a specific tool or visualization style.
Practical workflow
Шаги C4 workflow
5 этапов от границ системы до runtime-представленияКонтекст
Начинайте с System Context, чтобы зафиксировать границы и внешние зависимости.
Контейнеры
Добавляйте Container диаграмму как основной рабочий слой архитектуры.
Компоненты
Компоненты рисуйте только для важных/сложных контейнеров.
Код
Code-уровень оставляйте для сложных мест и генерируйте из кода.
Runtime + Infra
Для сценариев и среды развертывания используйте Dynamic и Deployment.
Контекст
Начинайте с System Context, чтобы зафиксировать границы и внешние зависимости.
Контейнеры
Добавляйте Container диаграмму как основной рабочий слой архитектуры.
Компоненты
Компоненты рисуйте только для важных/сложных контейнеров.
Код
Code-уровень оставляйте для сложных мест и генерируйте из кода.
Runtime + Infra
Для сценариев и среды развертывания используйте Dynamic и Deployment.
Common mistakes
Start too deep
Immediately start with component/code without context/container.
Blurred connections
Sign connections with general words like `uses` without specifics.
One poster for everything
Trying to show everything on one diagram and losing readability.
Manual L4 synchronization
Store code diagrams manually without auto-updating from sources.