C4 Model

Зачем

Архитектурная документация в команде обычно либо слишком общая (один прямоугольник «backend»), либо слишком детальная (UML на 50 классов, который никто не читает). C4 (Simon Brown, 2011) решает эту проблему одним приёмом: четыре уровня зума, каждый на свою аудиторию. Не «лучшая нотация», а общий язык: бизнес читает один уровень, разработчики — другой, security audit — третий, и все понимают одно и то же.

Без C4 типичная картина: на onboarding 2-4 недели уходит только на «что где запущено», PR review требует контекста которого нет, security audit невозможен потому что нет single source of truth по контейнерам и trust boundaries. C4 даёт минимальный обязательный набор: Context + Container — и онбординг сжимается до часов.

Mental model

«Карта мира → карта страны → карта города → карта района. Каждый уровень отвечает на свой вопрос. C4 — то же самое для software: системы → контейнеры → компоненты → код.»

Четыре уровня — это зум одной и той же системы, не четыре разные диаграммы про разное:

• L1 Context — наша система как чёрный ящик в окружении actors и external systems.
• L2 Container — что запущено внутри (SPA, API, БД, очередь). Container ≠ Docker.
• L3 Component — что внутри одного container (Controllers, Services, Repositories).
• L4 Code — классы. Почти всегда не нужен — IDE и так показывает.

Правило: обязательны L1 + L2, L3 по необходимости (≥10 модулей или критичный сервис), L4 почти никогда.

Что на диаграмме

Три уровня одного e-shop, наложенные «матрёшкой» сверху вниз:

• L1 Context (вверху): customer, admin (actors) → shop-system (чёрный ящик) → stripe, sendgrid (external). Одна страница, ≤10 элементов.
• L2 Containers (середина): drill в shop-system — spa (React в браузере), mobile-app, api-svc (Node.js на ECS), worker-svc, pg (Postgres RDS), redis (ElastiCache), sqs. Каждое соединение подписано протоколом (JSON/HTTPS, SQL, enqueue jobs).
• L3 Components (внизу): drill в api-svc — ctrl-orders → svc-orders → repo-orders, pay-adapter; ctrl-users → svc-users → repo-users. Маппится на packages/modules в коде.

Pulse-рёбра между уровнями (shop-system → spa, api-svc → ctrl-orders) — это визуальный «zoom-into», не настоящие data flows.

Сценарии

L1 System Context — старт всегда отсюда. Одна страница, 5-10 элементов, audience-agnostic: CEO, sales, новый сотрудник в первый день, external auditor — все читают и понимают что делает система. На L1 запрещено: внутренности (БД, очереди), микросервисный split, технологии. Stripe и SendGrid рисуются как external boxes — мы не контролируем их код. Actors — это роли (Customer, Admin, Support agent), не конкретные люди. Skipping L1 («все и так знают») — главный анти-паттерн: новые люди не знают, security audit тем более.

Drill L1 → L2 Container view. Раскрываем чёрный ящик: что запущено внутри. Container в C4 — это deployable unit, не Docker: SPA в браузере — container, mobile binary — container, managed RDS instance — container, S3 bucket — container. Audience сужается до developers + DevOps. Каждое соединение обязано иметь label с протоколом (JSON/HTTPS, SQL, Kafka topic orders.v1) — без него рецензент не понимает intent. Типичный размер: 7-15 боксов. Больше 20 — сигнал что система должна быть разбита на несколько Context-уровневых систем.

Drill L2 → L3 Component view. Раскрываем один container (здесь — API). Компоненты — это packages/modules в коде, не классы (классы это L4). Pattern из примера — Clean Architecture: Controller (HTTP layer) → Service (use case) → Repository (data access) + Adapter (порт к external Stripe в стиле Hexagonal). L3 нужен per-container (отдельная диаграмма для API, отдельная для worker). Skip если container тривиальный (2-3 модуля) — overkill.

Diagrams as Code workflow. Главное в C4 не нотация, а дисциплина обновления. Архитектор открывает docs/architecture/c4/workspace.dsl, добавляет es = container "Elasticsearch" + relationship api -> es "search query" "JSON/HTTPS", коммитит. CI (structurizr-cli export) рендерит Mermaid/PNG, прикладывает к PR comment. Reviewer видит diff в .dsl + rendered preview side-by-side. После merge — docs site обновляется автоматически. Render-время Structurizr CLI ~2s на 30-element workspace, CI overhead ~30s. Drag-drop в Confluence/Lucidchart — категорически нет: невозможно review через PR, vendor lock, gather dust через 6 месяцев.

Trade-offs (ADR-001, ADR-002)

В диаграмме зашиты два ADR — открой ноду shop-system (ADR-001) и svc-orders (ADR-002).

ADR-001: C4 как обязательный стандарт vs UML / ad-hoc box-and-arrow. UML (1997, OMG) определяет 14 типов диаграмм, в реальности используется 2-3 (class, sequence, иногда component) и каждый рисует по-своему. Ad-hoc «boxes & arrows» в Miro даёт 100% гибкости и 0% смысла без legend. Альтернативы: arc42 (German engineering template на 12 секций, часто комбинируется с C4), TOGAF/Archimate (enterprise overkill для product team), просто Mermaid (lightweight, но без чёткой ментальной модели уровней). Adoption публично: Spotify, ING, Adidas, BBC, FedEx; AWS Well-Architected рекомендует C4-style; OWASP threat modeling строится на C4 Container.

Решение: C4 обязателен, минимум L1+L2 для каждого bounded context. Container view ≠ Docker — это шире. Tooling tier: Structurizr DSL для главного workspace, Mermaid C4 для inline README, PlantUML только для legacy.

ADR-002: Diagrams as Code, рендер в CI. Drag-and-drop инструменты (Lucidchart, draw.io desktop, Confluence whiteboard) дают мгновенный visual feedback, но фундаментально несовместимы с инженерным workflow: нельзя review через PR (бинарный diff), легко забыть обновить (диаграмма отдельно от кода), vendor lock, нет single source of truth. Diagrams as code решает каждый пункт: текстовый файл в repo → diff в PR → рендер в CI → PNG/SVG к docs site.

Решение: docs/architecture/c4/workspace.dsl как single source для Context + Container + Component. CI workflow: при изменении docs/architecture/** или apps/**/Dockerfile или infra/terraform/** — structurizr-cli export → commit rendered Mermaid → PR comment с preview, failed render = blocking check. Каждый container и component обязан иметь description и technology; relationships обязаны иметь label с протоколом.

Реальные системы

• Spotify, ING, Adidas, BBC, FedEx — публичные доклады про C4 adoption как стандарта документации
• AWS Well-Architected Framework рекомендует C4-style diagrams для review-сессий
• OWASP threat modeling часто строится на C4 Container уровне (определяет trust boundaries)
• DDD Crew рекомендует C4 для bounded contexts visualization
• Structurizr customers — крупная база enterprise (BBC, FedEx и др.)
• CNCF проекты — часть документации использует C4-style

Tools tier (что выбирают в проде 2025):

Anti-patterns

• Skipping Level 1 — «все знают context» (нет, новые люди не знают; security audit тем более)
• Code level как обязательный — pure overhead; IDE и так показывает, нужен только при tricky inheritance/generics
• Один огромный diagram «вся архитектура» на 200 элементов — нечитаемо, никто не open после первого раза
• Color soup без legend — что значат синий и жёлтый? Каждая диаграмма обязана иметь title + key
• Connections без labels — рецензент не понимает протокол (REST? gRPC? Kafka topic?)
• Stale diagram (последний update 2022) — хуже чем отсутствие, потому что вводит в заблуждение
• Diagram в Confluence/Lucidchart облаке — невозможно review через PR, vendor lock, gather dust
• Путать Container с Docker container — Container в C4 шире: SPA в браузере, managed RDS, S3 bucket — все containers
• Внутренности на L1 (БД, очереди, микросервисы) — это L2, на L1 они отвлекают
• External system нарисован «внутри» нашей — Stripe не наш код, рисуем как external box
• Update Dockerfile/Helm/Terraform без update workspace.dsl — drift начинается здесь; CI должен warn
• Component diagram, ссылающийся на классы — это L4 Code, а не L3; на L3 — packages/modules

Когда НЕ использовать

• Solo project, throw-away prototype, hackathon — overhead не окупается, README + Mermaid Context хватит
• Однофайловый скрипт / CLI utility — нет «системы», нечего разбивать на уровни
• Команда из 1-2 человек на короткой дистанции — устная коммуникация эффективнее (но как только присоединяется 3-й — заводи L1)
• Полностью stateless serverless без external dependencies — Context-уровня обычно достаточно, Container может выродиться в один box
• Когда нужен runtime/network/data flow — C4 это про структуру, не про runtime: используй sequence diagrams (Dynamic view в Structurizr), network topology diagrams, event flow diagrams отдельно

Дальше читать

В этом курсе:

• [CONCEPT]architecture-decision-records — ADR motivates выбор containers/components; пара «ADR + Container diagram» в одной папке = full picture
• [CONCEPT]ddd-strategic — Container часто = bounded context; context maps похожи на C4 Container view
• [CONCEPT]clean-architecture — паттерн L3 Component (Controller → Service → Repository) пришёл отсюда
• [CONCEPT]event-storming — discovery workshop, выход которого можно прямо положить в L1 Context + первый набросок L2
• [CONCEPT]evolutionary-architecture — fitness functions могут проверять соответствие кода Container-диаграмме

Внешние источники:

• Simon Brown — c4model.com (официальный сайт, всё там)
• Simon Brown — Software Architecture for Developers (книга, leanpub)
• Structurizr — structurizr.com + structurizr/dsl
• C4-PlantUML — github.com/plantuml-stdlib/C4-PlantUML
• Mermaid C4 — mermaid.js.org/syntax/c4.html
• Birgitta Boeckeler (ThoughtWorks) — Diagram as Code
• arc42 — arc42.org (alternative documentation template, часто paired с C4 для diagrams)
• Simon Brown YouTube — «The Lost Art of Software Design»