1 апреля 2024
C4 Model - это способ визуализации архитектуры программных систем через четыре уровня абстракции: Context, Containers, Components, Code. Как карты Google: от страны до улицы.
Зачем нужен C4
Проблема архитектурных диаграмм - они либо слишком абстрактны (бессмысленные квадратики), либо слишком детальны (UML-простыни). C4 предлагает золотую середину: четыре уровня детализации для разных аудиторий.
- Context - для всех, включая бизнес
- Containers - для технической команды
- Components - для разработчиков
- Code - для глубокого погружения
Level 1: System Context
Показывает систему как чёрный ящик в окружении пользователей и внешних систем. Это bird's eye view - вид с высоты птичьего полёта.
| Scope | Одна software system |
| Primary elements | Ваша система (в центре) |
| Supporting elements | Пользователи (роли, персоны) и внешние системы |
| Аудитория | Все: технические и нетехнические люди |
Пример: B2B SaaS платформа
┌─────────────────────────────────────────────────────────────────┐
│ USERS (Personas) │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
│ Employee │ Client │ Admin │ Support │ SRE │
│ (firm user) │ (end user) │ (system) │ (L2 help) │ (ops) │
└──────┬──────┴──────┬──────┴──────┬──────┴──────┬──────┴────┬────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ │
│ ┌───────────────────┐ │
│ │ THE PLATFORM │ │
│ │ (Our System) │ │
│ └─────────┬─────────┘ │
│ │ │
└──────────────────────────────┼──────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Payment │ │ E-Signature │ │ Email │
│ Provider │ │ Service │ │ Integration │
└─────────────┘ └─────────────┘ └─────────────┘
EXTERNAL SYSTEMS (Third-Party Services)Что НЕ включать: технологии, протоколы, низкоуровневые детали. Диаграмма должна быть понятна product manager или CEO.
Level 2: Containers
Zoom-in внутрь системы. Показывает deployable units: веб-приложения, API, базы данных, очереди сообщений, мобильные приложения.
| Scope | Одна software system |
| Primary elements | Containers внутри системы |
| Supporting elements | Пользователи и внешние системы, связанные с containers |
| Аудитория | Технические люди: архитекторы, разработчики, DevOps |
Показывает:
- High-level структуру архитектуры
- Распределение ответственности
- Основные технологические решения
- Как containers общаются друг с другом
Пример: Backend платформы
CLIENT APPS: [React SPA] [Mobile Employee] [Mobile Client] [Desktop] [Admin]
| | | | |
+-------+------+-------+-------+-------------+---------+
| |
v HTTPS API v
+--------------------------------------------------+
| BACKEND |
| |
| +----------+ +------------+ +-----------+ |
| | Web App | | Background | | Scheduler | |
| | (Rails) | | Jobs | | (Cron) | |
| +----+-----+ +-----+------+ +-----+-----+ |
| | | | |
| +--------------+--------------+ |
| | |
| v |
| +----------------------------------------------+|
| | DATABASES ||
| | [PostgreSQL] [Redis] [OpenSearch] [S3] ||
| +----------------------------------------------+|
+--------------------------------------------------+
| | |
v gRPC v gRPC v gRPC
+---------+ +---------+ +-----------+
|Payments | | OCR | |Marketplace|
| Service | | Service | | Service |
+---------+ +---------+ +-----------+Что НЕ включать: кластеризацию, load balancers, репликацию - это для Deployment diagram.
Level 3: Components
Zoom-in внутрь одного container. Показывает структурные блоки: сервисы, контроллеры, репозитории и их взаимодействие.
| Scope | Один container |
| Primary elements | Components внутри container |
| Supporting elements | Другие containers и внешние системы |
| Аудитория | Архитекторы и разработчики |
Пример: Web Application container
+--------------------------------------------------------------+
| WEB APPLICATION (Rails) |
| |
| +--------------+ +--------------+ +------------------+ |
| | Controllers | | Services | | Background | |
| | | | | | Jobs | |
| | - Invoices |->| - Billing | | - PaymentSync | |
| | - Users | | - Payments |->| - ReportBuilder | |
| | - Reports | | - Analytics | | - Notifications | |
| +------+-------+ +------+-------+ +--------+---------+ |
| | | | |
| v v | |
| +--------------+ | |
| | Repositories |<------------+ |
| | | |
| | - UserRepo | |
| | - InvoiceRepo| |
| +------+-------+ |
| | |
+--------------------------------------------------------------+
|
v SQL
+--------------+
| PostgreSQL |
+--------------+Level 4: Code
Самый детальный уровень: UML-диаграммы классов, ER-диаграммы и т.д. В большинстве случаев не нужен - код сам себя документирует, а IDE позволяет навигировать по нему.
Когда полезен:
- Сложные алгоритмы, где визуализация помогает понять последовательность шагов
- Design patterns - наглядно показать связи между классами
- Критические части системы, которые редко меняются (ядро платёжной логики, state machine)
Для большинства проектов достаточно уровней 1-3. Если код хорошо структурирован и покрыт тестами, Level 4 создаёт больше работы по поддержанию актуальности, чем приносит пользы.
Дополнительные диаграммы
System Landscape Diagram
Когда нужно показать несколько систем в рамках организации. По сути - Context diagram без фокуса на конкретной системе.
| Scope | Enterprise / организация / департамент |
| Аудитория | Все |
Dynamic Diagram
Показывает взаимодействие элементов во время выполнения: user story, use case, конкретный сценарий. Похоже на UML sequence diagram, но с более свободной раскладкой.
| Scope | Конкретная feature / user story |
| Elements | На выбор: systems, containers или components |
Deployment Diagram
Показывает, как containers деплоятся на инфраструктуру: серверы, VM, Kubernetes, cloud services. Основан на UML deployment diagram.
| Scope | Одна или несколько систем в конкретном environment (prod, staging, dev) |
| Elements | Deployment nodes, container instances, infrastructure (DNS, load balancers, firewalls) |
| Аудитория | Архитекторы, разработчики, DevOps, SRE |
Можно использовать иконки AWS, Azure, GCP - но включайте их в легенду.
Рекомендации
Какие диаграммы создавать
| Диаграмма | Рекомендация |
|---|---|
| System Context | Да - для каждой системы |
| Container | Да - для каждой системы |
| Component | По необходимости |
| Code | Редко, только для сложных частей |
| Deployment | Да - как минимум для production |
Diagrams as Code
- Версионирование в Git
- Code review диаграмм через PR
- Автоматическое обновление при изменении архитектуры
- Единый источник правды
Я использую PlantUML с C4 extension. Пример Context диаграммы:
@startuml
!include <C4/C4_Context>
title My Platform - System Context
Person(employee, "Employee", "Firm user")
Person(client, "Client", "End user")
System(platform, "Platform", "Main system")
System_Ext(payments, "Payment Provider", "Processes payments")
System_Ext(email, "Email Service", "Sends notifications")
Rel(employee, platform, "Manages operations")
Rel(client, platform, "Uses services")
Rel(platform, payments, "Processes payments", "HTTPS")
Rel(platform, email, "Sends emails", "SMTP")
@endumlИнструменты
- PlantUML + C4 - мой выбор, отлично интегрируется с CI/CD
- Structurizr - DSL для C4 от автора модели
- Mermaid - C4 diagrams, рендерится в GitHub/GitLab
- draw.io - если нужен визуальный редактор
Советы
- Начинайте с Context - это фундамент понимания
- Не смешивайте уровни - каждая диаграмма должна быть на одном уровне абстракции
- Включайте легенду - особенно если используете нестандартные обозначения
- Обновляйте регулярно - устаревшая диаграмма хуже, чем её отсутствие
- Diagrams as code - версионируйте вместе с кодом
- Монолит vs Микросервисы - когда какая архитектура подходит