C4 Model: Практические принципы проектирования архитектуры ПО

Проблема, которую все игнорируют

Давайте честно: архитектурную документацию никто не читает. Она устаревает за неделю, живёт в Confluence как памятник прошлому, а новички получают знания через «а можно я у тебя спрошу?». Диаграммы превращаются в арт-объекты — красиво, но бесполезно.

C4 model от Simon Brown решает эту проблему элегантно: четыре уровня абстракции, как карты Google Maps. Можно смотреть на город с высоты птичьего полёта, можно спуститься до конкретной улицы. Каждый уровень отвечает на свой вопрос и полезен своей аудитории.

Я использую C4 во всех проектах начиная с 2019 года. Это не панацея, но лучшего инструмента для визуализации архитектуры я не встречал.

TL;DR: Кому и зачем читать

Эта статья для разных ролей даёт разную ценность. Вот что вы найдёте:

👨‍💻 Разработчик (Junior → Middle)

Прочитай: Level 1-3, Практические правила, Типовые грабли

Зачем: Поймёшь, как устроена система, куда класть новый код, как читать архитектурные диаграммы

Время: 10 минут

Польза: Сократишь онбординг с 3 недель до 3 дней, перестанешь бояться "большой картины"

🏗️ Архитектор / Tech Lead

Прочитай: Всё + раздел CJM+C4, Продвинутые техники, Автоматизация

Зачем: Научишься проектировать архитектуру, которую понимает вся команда, связывать UX с техническими решениями

Время: 30 минут

Польза:

• Ускоришь принятие архитектурных решений с 5 дней до 1 дня
• Получишь фреймворк для связки CJM и архитектуры
• Научишься автоматизировать документацию

💼 CTO / Engineering Manager

Прочитай: TL;DR, ROI метрики, Реальные кейсы, Чек-лист внедрения

Зачем: Получишь цифры и процесс для внедрения архитектурной дисциплины в команде

Время: 15 минут

Польза:

• −87% времени на онбординг новых разработчиков
• −80% ошибок из-за непонимания архитектуры
• −75% времени на документацию (за счёт автоматизации)
• Прозрачность архитектуры для всех стейкхолдеров

🎨 Product Manager / UX Designer

Прочитай: Раздел C4 + CJM, Level 1-2

Зачем: Поймёшь, как твои user journey превращаются в техническую архитектуру

Время: 15 минут

Польза: Научишься валидировать CJM через техническую реализацию, находить зазоры между обещаниями и возможностями

Быстрый старт: Если у вас только 1 час на C4

Нет времени читать всю статью? Вот экспресс-план.

5 обязательных вещей (60 минут)

1. Создайте файл docs/architecture/system-context.md (10 мин)

# Архитектура: System Context
 
## Наша система
 
[Название вашего продукта] — [одно предложение, что делает]
 
## Пользователи
 
- **[Роль 1]**: [что делает]
- **[Роль 2]**: [что делает]
 
## Внешние системы
 
- **[Система 1]**: [зачем интегрируемся]
- **[Система 2]**: [зачем интегрируемся]
 
## Диаграмма
 
[Нарисуйте в Mermaid или вставьте скриншот с доски]

2. Нарисуйте Level 1 на доске/Miro (15 мин)

• Один квадрат — ваша система
• Человечки — роли пользователей
• Квадраты — внешние системы
• Стрелки с подписями: кто с кем общается

3. Создайте Level 2: Containers (20 мин)

• Какие приложения/сервисы у вас есть?
• Базы данных, очереди, кеши
• Как они связаны?

Используйте Mermaid Live Editor — вставляете текст, получаете диаграмму.

4. Добавьте технологии в квадратные скобки (5 мин)

• Web App [React + Next.js]
• API [Python + FastAPI]
• Database [PostgreSQL 15]

5. Положите в README.md главного репозитория (10 мин)

## Архитектура
 
См. [docs/architecture/system-context.md](docs/architecture/system-context.md)
 
**Быстрый обзор:**
 
- Level 1 (Context): [ссылка на диаграмму]
- Level 2 (Containers): [ссылка на диаграмму]

3 смертных греха (чего НЕ делать)

❌ Грех #1: Рисовать диаграммы в PowerPoint/draw.io или хранить в Confluence/Wiki

• Почему плохо: невозможно версионировать вместе с кодом, устаревает через неделю
• Что делать: Только Diagrams as Code в Git-репозитории проекта. Mermaid, PlantUML, Structurizr DSL
• Правило: Если диаграмма не в том же репо, где код — она уже устарела

❌ Грех #2: Делать диаграммы "для галочки" и складывать в отдельное место

• Почему плохо: никто не будет использовать, команда даже не знает, что они есть
• Что делать:
  • Хранить в корне проекта: /docs/architecture/
  • Линковать из README.md первой ссылкой
  • Презентовать на каждом onboarding'е
  • Обновлять в том же PR, что и код

❌ Грех #3: Рисовать Level 3-4 для всего подряд на старте

• Почему плохо: трата времени, детали устареют, команда перестанет доверять
• Что делать: Level 1-2 сначала, Level 3 — только для сложных частей по мере необходимости

3 аргумента, чтобы убедить команду

Для разработчиков: "Новички будут въезжать за 3 дня вместо 3 недель. Меньше вопросов 'а как тут всё работает?'"

Для менеджеров: "ROI 1,735% в первый год. Окупается через месяц. Вот таблица с цифрами [ссылка на раздел ROI]"

Для CTO: "Прозрачность архитектуры для инвесторов, аудиторов, партнёров. Один взгляд — вся картина"

Что такое C4 Model

C4 расшифровывается как Context, Containers, Components, Code — четыре уровня абстракции для описания архитектуры программных систем.

Философия C4

Ключевая идея: архитектура как карта местности с разными масштабами.

• Уровень 1 (Context): Вид с самолёта — система в окружении пользователей и других систем
• Уровень 2 (Containers): Вид города — из каких крупных частей состоит система
• Уровень 3 (Components): Вид улицы — из чего состоит каждая часть
• Уровень 4 (Code): Планировка здания — классы, интерфейсы, структуры

Принципы, которые делают C4 работающим

1. Абстракция через масштаб — каждый уровень полезен сам по себе
2. Аудитория и цель — диаграммы для людей, не для красоты
3. Эволюция вместо статики — диаграммы должны обновляться как код
4. Минимализм — только важное, без информационного шума
5. Единообразие нотации — одинаковые обозначения на всех уровнях

Личное мнение: IDEF-0 и чувство déjà vu

C4 — это, по сути, изобретение велосипеда. Идея многоуровневой абстракции не нова: IDEF-0 делал это 40 лет назад, UML Component Diagrams — 25 лет назад, 4+1 Architectural View Model от Kruchten — тоже не вчера родился.

Но! Это déjà vu не снимает плюсов C4. Почему C4 выстрелил там, где IDEF-0 остался нишевым инструментом?

1. Простота входа: IDEF-0 требовал обучения и сертификации, C4 можно освоить за час
2. Современный контекст: облака, микросервисы, DevOps — C4 говорит на языке сегодняшнего дня
3. Diagrams as Code: IDEF-0 рисовали в специализированных редакторах, C4 живёт в Git
4. Прагматизм vs формализм: C4 не требует строгости IDEF-0, он гибче и дружелюбнее

Так что да, C4 — это новая упаковка старых идей. Но иногда именно упаковка решает, будет ли инструмент использоваться или пылиться в учебниках по системному анализу.

Сравнительная таблица: C4 vs другие методологии

Чтобы было понятно, чем C4 отличается от конкурентов, вот честное сравнение:

Когда выбрать C4:

• Нужно быстро начать (стартап, MVP)
• Команда хочет простоту и практичность
• Есть микросервисы или планируются
• Хотите Diagrams as Code в Git
• Нужна интеграция с CI/CD

Когда выбрать ArchiMate:

• Enterprise с жёсткими стандартами
• Нужна сертификация и compliance
• Описываете не только IT, но и бизнес-процессы
• Готовы изучать сложную нотацию (есть бесплатный Archi, есть платные Sparx Enterprise Architect, BiZZdesign)

Когда выбрать UML:

• Описываете объектно-ориентированную систему
• Нужны детальные class diagrams
• Команда уже знает UML
• Академическая среда / обучение

Когда выбрать IDEF-0:

• Госпроект с требованием по ГОСТу
• Описываете производственные процессы
• Нужна строгая формализация
• Есть legacy стандарты компании

Когда выбрать 4+1:

• Нужны разные view для разных стейкхолдеров
• Сложная система с множеством аспектов
• Комбинируете с другими нотациями

Level 1: System Context — Вид с высоты птичьего полёта

Зачем нужен

Контекстная диаграмма отвечает на вопросы:

• Кто использует систему?
• С какими внешними системами она взаимодействует?
• Каковы границы ответственности?

Аудитория: все — от бизнеса до разработчиков.

Что включаем

• Вашу систему (один квадрат в центре)
• Пользователей (роли, не конкретных людей)
• Внешние системы (платёжки, CRM, почтовые сервисы)
• Взаимодействия (кто с кем и зачем общается)

Пример: Платформа онлайн-обучения

Практические правила

Антипаттерны:

• ❌ Раздувать Context до уровня Containers — «а давайте тут покажем базы данных»
• ❌ Показывать внутреннюю структуру — для этого Level 2
• ❌ Технические детали протоколов — это не здесь

Level 2: Container Diagram — Архитектурное зонирование

Зачем нужен

Container-диаграмма раскрывает систему на крупные блоки:

• Из каких приложений/сервисов состоит система?
• Как они взаимодействуют?
• Какие технологии используются?

Аудитория: архитекторы, тимлиды, DevOps, старшие разработчики.

Что включаем

• Веб-приложения (SPA, MPA)
• Мобильные приложения (iOS, Android)
• Бэкенд-сервисы (API, воркеры)
• Базы данных (SQL, NoSQL, кеши)
• Очереди сообщений (Kafka, RabbitMQ)
• Внешние системы (из Level 1)

Пример: Та же платформа обучения

Практические правила

Что показывать:

• Технологический стек в подписи: API Gateway [Kong]
• Протоколы взаимодействия: HTTP/REST, gRPC, GraphQL, AMQP
• Реплицируемые базы данных как отдельные контейнеры (если это важно)

Принципы группировки:

• Если можно развернуть отдельно — это Container
• Если масштабируется независимо — это Container
• Если у него свой CI/CD пайплайн — точно Container

Зачем указывать технологии

Это не академическая педантичность. Технологии на Container-диаграмме:

• Помогают новичкам понять стек проекта за 30 секунд
• Выявляют зоопарк — если у вас 7 языков программирования, может, пора задуматься?
• Упрощают оценку — архитектор сразу видит сложность интеграций

Level 3: Component Diagram — Внутренности контейнера

Зачем нужен

Component-диаграмма показывает структуру одного Container:

• Какие модули/компоненты внутри?
• Какие обязанности у каждого?
• Как они взаимодействуют?

Аудитория: разработчики, тимлиды, архитекторы (для детального дизайна).

Что включаем

• Компоненты — логические модули с чёткой ответственностью
• Интерфейсы — публичные API компонентов
• Зависимости — кто от кого зависит
• Внешние зависимости — базы, очереди, другие контейнеры

Пример: Course Service изнутри

Практические правила

Что такое Component в C4:

• Группа связанных функций/классов с чёткой ответственностью
• Имеет публичный интерфейс (API)
• Может быть заменён альтернативной реализацией

Примеры компонентов:

• Controllers (MVC)
• Services / Use Cases
• Repositories / Data Access
• Gateways / Adapters
• Middleware / Interceptors

Антипаттерны Level 3

• ❌ Слишком детально: показывать каждый класс — это уже Level 4
• ❌ Слишком абстрактно: «Business Logic» как один квадрат — бесполезно
• ❌ Смешивать слои: UI-компоненты и бизнес-логику на одном уровне абстракции

Правильная гранулярность: 5–12 компонентов на диаграмме. Меньше — объединяйте, больше — декомпозируйте Container или группируйте компоненты.

Level 4: Code — Детали реализации

Зачем нужен (спойлер: часто не нужен)

Code-диаграммы показывают классы, интерфейсы, структуры данных. Это UML class diagrams.

Проблема: эти диаграммы устаревают быстрее, чем вы успеваете их нарисовать.

Решение C4: используйте инструменты автогенерации (PlantUML, Structurizr, IDE-плагины) или вообще замените Code-диаграммы на хороший README в модуле.

Когда Level 4 полезен

• Сложные паттерны проектирования (Strategy, Visitor, Builder)
• Публичные API библиотек
• Критичная бизнес-логика с неочевидными связями

Пример (упрощённый)

Практические принципы применения C4

1. Диаграммы как код (Diagrams as Code)

Рисовать в draw.io/Visio/PowerPoint — путь в ад поддержки. Почему?

• ❌ Невозможно версионировать вместе с кодом
• ❌ Не видно изменений в git diff
• ❌ Невозможно автоматизировать генерацию
• ❌ Сложно обновлять (открыть файл, отредактировать, сохранить, закоммитить)
• ❌ Конфликты при одновременном редактировании

Единственно правильный подход: хранить диаграммы как текстовые файлы в том же репозитории, где код. Почему это работает?

• ✅ Версионируются вместе с кодом (один коммит = код + диаграммы)
• ✅ Ревьюятся в Pull Request'ах как обычный код
• ✅ Изменения видны в git diff: "добавили Redis — появился на диаграмме"
• ✅ Можно автоматически генерировать из кода/конфигов
• ✅ CI/CD может проверять актуальность
• ✅ Легко обновлять (просто редактируешь текст)

Используйте текстовые форматы:

Инструменты:

• Structurizr (DSL от автора C4) — лучший выбор для серьёзных проектов
• PlantUML — популярный, гибкий, но синтаксис не для слабонервных
• Mermaid — простой, интегрируется везде (GitHub, GitLab, Notion)
• Diagrams (Python) — code-first подход для инфраструктуры

Пример на Structurizr DSL:

workspace {
    model {
        student = person "Студент"
        instructor = person "Преподаватель"

        lms = softwareSystem "LMS" {
            webapp = container "Web App" "React + Next.js"
            api = container "API Gateway" "Kong"
            courseService = container "Course Service" "Python + FastAPI"
            db = container "PostgreSQL" "Database"
        }

        bank = softwareSystem "Bank" "Платёжная система"

        student -> webapp "Проходит курсы"
        webapp -> api "JSON/HTTPS"
        api -> courseService "HTTP"
        courseService -> db "SQL"
        courseService -> bank "Обрабатывает платежи"
    }

    views {
        systemContext lms {
            include *
            autolayout lr
        }

        container lms {
            include *
            autolayout lr
        }
    }
}

2. Храните диаграммы рядом с кодом

Структура, которая работает:

/docs
  /architecture
    /c4
      00-legend.md          # Легенда обозначений
      01-system-context.dsl # Level 1
      02-containers.dsl     # Level 2
      03-components/        # Level 3 для отдельных контейнеров
        course-service.dsl
        auth-service.dsl
      diagrams/             # Сгенерированные изображения (PNG/SVG)

Почему это единственный работающий подход:

1. Синхронизация: Код изменился → диаграммы обновились в том же PR
2. История: git log показывает эволюцию архитектуры параллельно с кодом
3. Ревью: Архитектор видит на code review: "Добавили сервис, но не обновили C4 Level 2"
4. Автоматизация: CI/CD генерирует PNG из DSL при каждом коммите
5. Доступность: Клонировал репо → получил актуальную архитектуру
6. Offline-доступ: Архитектура всегда под рукой, не зависит от сети/VPN

Антипаттерн: Confluence/SharePoint/Wiki

Почему внешние wiki не работают:

• Разработчик обновил код → забыл обновить wiki (в 95% случаев)
• Wiki живёт отдельно → устаревает мгновенно
• Нет code review для документации
• Нет версионирования → не видно, что изменилось
• Нужен VPN/доступ к корпоративной сети → неудобно

3. Делайте диаграммы живыми

Подход 1: Генерация из кода

• Annotation-based (Java Spring, NestJS)
• Рефлексия (Python, C#)
• AST parsing (JavaScript, TypeScript)

Подход 2: Проверка соответствия через тесты

Пример: проверяем, что все сервисы из docker-compose/kubernetes упомянуты в C4 диаграммах.

import yaml
import pytest
 
def test_all_services_documented_in_c4():
    """Проверяем, что все сервисы из docker-compose есть в C4 Level 2"""
 
    # Читаем реальные сервисы из docker-compose.yml
    with open("docker-compose.yml") as f:
        compose = yaml.safe_load(f)
        actual_services = set(compose["services"].keys())
 
    # Читаем задокументированные сервисы из C4 диаграммы
    with open("docs/architecture/02-containers.md") as f:
        c4_content = f.read()
        # Ищем упоминания сервисов (простой парсинг)
        documented_services = set()
        for line in c4_content.split("\n"):
            if "[" in line and "]" in line:
                # Извлекаем имя сервиса (до [Technology])
                service = line.split("[")[0].strip("- ").lower().replace(" ", "-")
                documented_services.add(service)
 
    # Проверяем соответствие
    undocumented = actual_services - documented_services
 
    assert len(undocumented) == 0, (
        f"Сервисы не задокументированы в C4 Level 2: {undocumented}\n"
        f"Обновите docs/architecture/02-containers.md"
    )
 
def test_no_phantom_services_in_c4():
    """Проверяем, что в C4 нет сервисов, которых уже нет в коде"""
 
    # Обратная проверка: защита от устаревшей документации
    with open("docker-compose.yml") as f:
        compose = yaml.safe_load(f)
        actual_services = set(compose["services"].keys())
 
    with open("docs/architecture/02-containers.md") as f:
        c4_content = f.read()
        documented_services = set()
        for line in c4_content.split("\n"):
            if "container" in line.lower() and "[" in line:
                service = line.split("[")[0].strip("- ").lower().replace(" ", "-")
                documented_services.add(service)
 
    phantom_services = documented_services - actual_services
 
    assert len(phantom_services) == 0, (
        f"В C4 есть сервисы, которых нет в docker-compose: {phantom_services}\n"
        f"Устаревшая документация! Удалите из C4 диаграммы"
    )

Такой тест запускается в CI и падает, если:

• ✅ Добавили новый сервис → тест требует обновить C4
• ✅ Удалили сервис → тест требует убрать из C4
• ✅ Документация всегда синхронизирована с кодом

Подход 3: CI/CD automation

# .gitlab-ci.yml
generate-architecture-diagrams:
  stage: docs
  script:
    - structurizr-cli export -workspace docs/architecture/workspace.dsl -format png
    - cp exports/*.png docs/diagrams/
  artifacts:
    paths:
      - docs/diagrams/

4. Легенда и соглашения

Создайте файл LEGEND.md в начале проекта:

# C4 Диаграммы: Легенда
 
## Обозначения
 
- 🟦 **Синий прямоугольник** — наши контейнеры/компоненты
- 🟩 **Зелёный прямоугольник** — внешние системы
- 👤 **Человечек** — пользователи (роли)
- 🗄️ **Цилиндр** — база данных
- 📨 **Ромб** — очередь сообщений
 
## Протоколы
 
- **Сплошная стрела** — синхронное взаимодействие (HTTP, gRPC)
- **Пунктирная стрела** — асинхронное (очереди, события)
 
## Технологии
 
Всегда указываем в квадратных скобках:
 
- `API Gateway [Kong]`
- `Course Service [Python + FastAPI]`
- `Database [PostgreSQL 15]`

5. Аудитория и глубина

Практическое правило:

• Стартап/MVP: достаточно Level 1 + Level 2
• Средний проект: добавьте Level 3 для сложных сервисов
• Enterprise: все уровни, но автоматизируйте Level 4

6. Обновление и актуальность

Процесс:

1. Архитектурные изменения → обновляем C4 диаграммы в той же ветке
2. Код-ревью проверяет соответствие диаграмм и кода
3. Definition of Done включает обновление документации

Автоматизация:

# Pre-commit hook
#!/bin/bash
if git diff --cached --name-only | grep -q "src/services/"; then
    echo "⚠️  Изменения в сервисах. Не забудьте обновить C4 диаграммы!"
    echo "📁 docs/architecture/c4/"
fi

Типовые грабли и как их избегать

Грабли #1: Слишком много деталей на одной диаграмме

Симптом: Диаграмма не влезает на экран, 50+ элементов, никто не может понять.

Решение:

• Разбейте на несколько диаграмм по доменам
• Используйте группировку (subgraphs в Mermaid)
• Создайте "overview" диаграмму + детальные для каждой части

Грабли #2: Устаревшие диаграммы

Симптом: «У нас есть диаграммы, но они двухлетней давности».

Решение:

• Diagrams as Code в том же Git-репозитории, что и код (обязательно!)
• Диаграммы обновляются в том же Pull Request, что и код
• в Pull Request template есть пункт в чеклисте: Обновлены архитектурные диаграммы (если нужно)
• Автоматическая генерация из кода/конфигов где возможно
• CI проверка: диаграммы обновлены в последние 30 дней

Грабли #3: «Нарисую потом»

Симптом: Проект живёт год, архитектура только в головах.

Решение:

• Level 1 + Level 2 на старте проекта (макс. 2 часа работы)
• Обновляйте инкрементально, а не «большим рефакторингом документации»

Грабли #4: Путаница уровней

Симптом: На Container-диаграмме показываются классы, на Component — базы данных как равноправные компоненты.

Решение:

• Держите в голове масштаб: Context → Containers → Components → Code
• Если непонятно, куда отнести элемент — смотрите на аудиторию диаграммы

Грабли #5: Диаграммы ради диаграмм

Симптом: Красиво, но никто не смотрит и не использует.

Решение:

• Используйте диаграммы на onboarding'е новичков
• Линкуйте из README и Architecture Decision Records (документы с архитектурными решениями)
• Проецируйте на архитектурных ревью

Грабли #6: C4 как религия

Симптом: Pull Request задерживается на 2 дня, потому что на код-ревью спорят о цвете стрелки на диаграмме. Команда тратит больше времени на рисование диаграмм, чем на написание кода.

Реальная история: Видел проект, где архитектор требовал обновления всех 4 уровней C4 для добавления одного endpoint'а. Скорость разработки упала в 3 раза. Команда начала ненавидеть C4.

Решение:

• Договоритесь о разумном балансе: не каждое изменение требует обновления диаграмм
• Level 1-2 обновляются при значимых архитектурных изменениях
• Level 3 — опционально, только для сложных компонентов
• Level 4 — почти никогда вручную
• Правило: если диаграмма не помогает принять решение — она не нужна

Грабли #7: Иллюзия ясности

Симптом: Диаграммы показывают структуру (какие компоненты есть), но не поведение (как они работают вместе). Новичок смотрит на C4 и всё равно не понимает, что происходит при оплате заказа.

Проблема: C4 отлично показывает ЧТО есть в системе, но плохо показывает КАК оно работает. Статичные диаграммы не раскрывают последовательность действий, условия, альтернативные пути.

Решение: Дополняйте C4 динамическими диаграммами для критичных сценариев:

• Sequence diagrams (UML) для сложных флоу
• Event Storming результаты для event-driven систем
• Flowcharts для бизнес-логики с ветвлениями

Пример: для сценария "Оплата курса" у вас должно быть:

• C4 Level 2: какие сервисы участвуют (Payment Service, Course Service, Notification Service)
• Sequence diagram: в каком порядке они вызываются, что происходит при ошибке платежа

Грабли #8: Архитектура для галочки

Симптом: C4 диаграммы рисует архитектор в одиночку, складывает в Confluence и забывает. Команда даже не знает, что они существуют. На вопрос "а как у нас устроена аутентификация?" — открывают код, а не диаграммы.

Реальная история: Компания потратила 3 месяца на детальную документацию архитектуры в C4 (Level 1-4 для всех сервисов). Красивые диаграммы, правильная нотация. Через полгода проверил — ни один разработчик не открывал эти диаграммы. Они устарели за неделю после создания.

Решение:

• Делайте диаграммы вместе с командой, а не для команды
• Включите их в Definition of Done: "Архитектурная диаграмма обновлена и презентована команде"
• Используйте на ежедневных практиках:
  • Onboarding новичков (день 1 — показываем C4)
  • Архитектурные ревью (проецируем на экран)
  • Planning встречи (рисуем на доске, где новая фича на диаграмме)
• Линкуйте из README проекта: первая ссылка — на C4 Level 1

Грабли #9: Преждевременная детализация

Симптом: Проект в MVP стадии (2 разработчика, 1 месяц до релиза), а архитектор уже нарисовал Component Diagrams (Level 3) для всех будущих микросервисов на 2 года вперёд.

Проблема: Детальные диаграммы для гипотетической архитектуры — трата времени. Через месяц всё изменится, диаграммы устареют, а время потеряно.

Решение:

• Стартап/MVP: достаточно Level 1 на салфетке + Level 2 в Mermaid
• Растущий проект: добавляйте Level 3 только когда сервис реально сложный и непонятный
• Enterprise: детализация только для критичных компонентов (платежи, безопасность, интеграции)

Правило: Рисуйте диаграммы just in time, а не just in case.

Грабли #10: Забыли про безопасность

Симптом: Красивые C4 диаграммы показывают все сервисы, базы данных, API... и случайно попадают в публичный репозиторий на GitHub. Или в презентацию на конференции. Поздравляю, вы только что рассказали всему миру, как обойти вашу защиту.

Проблема: C4 диаграммы содержат чувствительную информацию:

• Топология сети и security boundaries
• Используемые технологии и версии (база для поиска уязвимостей)
• Точки интеграции с внешними системами
• Архитектурные слабости

Решение:

• Храните детальные C4 диаграммы в приватных репозиториях
• Для публичных презентаций создавайте упрощённые версии (без технологий, без IP, без деталей)
• Обозначайте security boundaries на Level 2: DMZ, VPC, Trust Zones
• Добавляйте watermark: "CONFIDENTIAL — Internal Use Only"
• Не коммитьте в Git конфигурации с реальными хостами и credentials (даже в диаграммах)

Реальные кейсы применения

Кейс 1: Монолит → Микросервисы

Проблема: Команда из 40 человек, монолит на 500k строк кода, хотят выделить микросервисы.

Решение с C4:

1. Level 1: Показали текущий монолит и внешние системы
2. Level 2: Декомпозировали монолит на логические Containers (будущие сервисы)
3. Level 3: Для каждого сервиса показали внутренние компоненты
4. Миграция: Двигались по приоритетам, обновляя диаграммы после каждого выделенного сервиса

Результат: За 8 месяцев выделили 12 сервисов. C4 диаграммы были единственным источником правды о текущем состоянии архитектуры.

Кейс 2: Onboarding новых разработчиков

Проблема: Новички тратят 2–3 недели, чтобы понять «как тут всё устроено».

Решение с C4:

• День 1: показываем Level 1 (контекст системы)
• День 2: Level 2 (какие сервисы за что отвечают)
• Неделя 1: Level 3 для команды, в которую попал разработчик

Результат: Onboarding сократился до 1 недели. Диаграммы стали частью welcome-документации.

Кейс 3: Документация для аудита и комплаенса

Проблема: Банковская система, регуляторы требуют актуальную архитектурную документацию.

Решение с C4:

• Level 1–2 генерировались из Terraform + Kubernetes манифестов
• Level 3 обновлялся вручную для критичных сервисов
• CI/CD проверял соответствие диаграмм реальности

Результат: Прошли аудит с первого раза, документация всегда актуальна.

ROI от внедрения C4: Реальные цифры

Для CTO и Engineering Manager'ов — вот конкретные метрики из моих проектов.

Таблица "До/После" внедрения C4

Финансовый эффект (команда 15 человек)

Затраты на внедрение:

• Обучение команды: 8 часов (1 день workshop)
• Создание базовых диаграмм Level 1-2: 16 часов
• Настройка автоматизации (CI/CD): 8 часов
• Итого: ~32 часа (4 человеко-дня)

Экономия в первый год:

• Сокращение времени онбординга: ~12 дней × 6 новичков × $400/день = $28,800
• Сокращение времени на документацию: 4 часа/неделю × 52 недели × $50/час = $10,400
• Меньше ошибок в production: ~8 критических багов × $2000 (среднее время на фикс) = $16,000
• Ускорение принятия решений: ~50 решений × 3 дня × 3 человека × $400/день = $180,000

ROI первого года: ~$235,000 экономии на затраты $12,800 (32 часа × $400) = 1,735% ROI

Качественные улучшения (сложно измерить, но очень ценно)

Для команды:

• ✅ Снижение стресса у новичков — есть "карта местности"
• ✅ Больше уверенности при рефакторинге — видны зависимости
• ✅ Меньше споров на код-ревью — есть единый источник правды
• ✅ Проще планировать миграции и выделение сервисов

Для бизнеса:

• ✅ Прозрачность для стейкхолдеров — CTO может показать CEO "вот как всё работает"
• ✅ Ускорение найма — кандидаты быстрее понимают систему на интервью
• ✅ Снижение bus factor — знания не в головах, а в диаграммах
• ✅ Упрощение аудитов и compliance

Для продукта:

• ✅ Быстрее Time to Market для новых фич
• ✅ Меньше технического долга — архитектурные решения осознанные
• ✅ Проще интеграции с партнёрами — можно показать Level 1-2
• ✅ Лучше оценки сложности — видна полная картина

Метрики для разных размеров команды

Как измерять эффект от C4 в вашей команде

Базовые метрики (измеряйте ДО и ПОСЛЕ):

1. Onboarding time: Засеките время от первого дня до первого production PR у последних 3 новичков
2. Architecture questions: Подсчитайте вопросы про архитектуру в Slack/комментариях к PR за неделю
3. Decision time: Запишите длительность последних 5 архитектурных дискуссий
4. Documentation time: Засеките время, потраченное на обновление документации за спринт

Продвинутые метрики (если есть аналитика):

5. Deployment confidence: Опросите команду по шкале 1-10, насколько уверенно они деплоят изменения
6. Knowledge distribution: Скольким людям нужно заболеть, чтобы проект встал? (Bus factor)
7. Refactoring frequency: Как часто делаете рефакторинг без страха сломать всё?

Чек-лист измерений:

• Записали baseline метрики за месяц до внедрения C4
• Внедрили C4 Level 1-2
• Через месяц замерили те же метрики
• Через 3 месяца повторили измерения (для устойчивого эффекта)
• Представили цифры руководству с конкретным ROI

Когда C4 не нужен (честно)

Малые проекты

• Лендинги, простые CRUD-приложения
• Команда 1–2 человека
• Жизненный цикл < 6 месяцев

Альтернатива: README с текстовым описанием архитектуры.

Прототипы и MVP

• Архитектура меняется каждую неделю
• Цель — проверить гипотезу, а не построить систему

Альтернатива: Whiteboard-фото после архитектурных сессий.

Очень стабильные системы

• Легаси-монолит, который не меняется годами
• Нет новых разработчиков

Альтернатива: Если документация не нужна, не делайте её ради галочки.

Инструменты и экосистема

Лучшие инструменты для C4

Tier 1: Профессиональные

• Structurizr — DSL от Simon Brown, лучший выбор для больших проектов
• IcePanel — C4 в браузере с коллаборацией
• Archi — бесплатный open-source для enterprise

Tier 2: Универсальные

• PlantUML — text-to-diagram, C4 через плагин
• Mermaid — встроен в GitHub/GitLab/Notion
• draw.io — если очень хочется мышкой (но не стоит)

Tier 3: Специализированные

• c4builder — CLI-генератор
• Backstage + C4 plugin — интеграция в developer portal
• C4 DSL Model Extension — плагин для VS Code от VimpelCom (C4-VARP), презентовался на недавней конференции по архитектуре, удобен для работы с C4 DSL прямо в редакторе

Интеграции

# GitHub Actions: генерация диаграмм при каждом коммите
name: Generate C4 Diagrams
on: [push]
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate diagrams
        run: |
          docker run -v $(pwd):/workspace structurizr/cli \
            export -workspace /workspace/docs/c4/workspace.dsl \
            -format png -output /workspace/docs/diagrams
      - name: Commit diagrams
        run: |
          git config user.name "C4 Bot"
          git add docs/diagrams/
          git commit -m "Update C4 diagrams [skip ci]"
          git push

План внедрения C4: Неделя за неделей

Полноценное внедрение для команды 10-30 человек.

Неделя 1: Foundation

День 1-2: Workshop с командой (4 часа)

• Презентация C4 model (30 мин)
• Совместное рисование Level 1 на доске (1 час)
• Совместное рисование Level 2 (1.5 часа)
• Договоренности о том, как будем обновлять (30 мин)

День 3: Инструменты и процессы (2 часа)

• Создать docs/architecture/c4/ в репозитории
• Настроить Mermaid/PlantUML/Structurizr
• Добавить LEGEND.md с обозначениями
• Создать PR template с чекбоксом "Обновил диаграммы?"

День 4-5: Документирование (4 часа)

• Перенести диаграммы с доски в код (Mermaid/DSL)
• Добавить технологии и протоколы
• Линковать из README
• Ревью с командой

Результат недели 1:

• ✅ Level 1 + Level 2 в Git
• ✅ Команда знает, где диаграммы и как их читать
• ✅ Процесс обновления договорён

Неделя 2: Integration

День 1: Onboarding (2 часа)

• Добавить C4 в onboarding-чеклист
• Провести first onboarding session с диаграммами (если есть новичок)
• Собрать фидбек: что непонятно?

День 2-3: Level 3 для критичных частей (4 часа)

• Выбрать 2-3 самых сложных сервиса
• Нарисовать Component Diagrams
• Обсудить с командой, которая их поддерживает

День 4: Автоматизация базовая (2 часа)

• Pre-commit hook: напоминание обновить диаграммы
• Или CI проверка: диаграммы обновлены в последние 30 дней

День 5: Ретро (1 час)

• Что работает?
• Что мешает?
• Нужны ли изменения в процессе?

Результат недели 2:

• ✅ Level 3 для сложных частей
• ✅ C4 встроен в onboarding
• ✅ Базовая автоматизация

Неделя 3-4: Adoption

Неделя 3: Использование в повседневной работе

• Архитектурные ревью с проецированием диаграмм
• Planning: "Где на Level 2 будет новая фича?"
• Code review: "Обнови Level 2, добавили новый сервис"

Неделя 4: Оптимизация

• Замерить метрики "после": onboarding time, architecture questions
• Собрать фидбек от команды
• Улучшить процесс на основе фидбека

Месяц 2-3: Автоматизация и масштабирование

• CI/CD генерация диаграмм из кода (если возможно)
• Integration с Backstage/Service Catalog
• Автоматическая проверка architecture drift

Результат через 3 месяца:

• ✅ C4 — часть процесса разработки
• ✅ Команда обновляет диаграммы без напоминаний
• ✅ Новички используют диаграммы с первого дня
• ✅ Измеримый ROI (см. раздел метрик)

Чек-лист готовности

Проверьте себя через месяц после внедрения:

• Диаграммы обновлены в последние 2 недели
• Последний новичок использовал C4 на onboarding'е
• В последнем PR архитектурные изменения отражены в диаграммах
• На последнем архитектурном ревью использовали C4
• Команда знает, где диаграммы (95%+ в опросе)
• Диаграммы помогли принять хотя бы одно решение в последний месяц

Если все галочки стоят — C4 внедрён успешно. Если нет — смотрите раздел "Мои ошибки с C4" и корректируйте процесс.

Как C4 сочетается с другими практиками

C4 + Event Storming

Event Storming → определяем домены и bounded contexts

C4 Level 2 → показываем эти домены как Containers

C4 Level 3 → детализируем внутреннюю структуру каждого домена

C4 + ADR (Architecture Decision Records)

Что такое ADR: ADR — это markdown-документы, фиксирующие важные архитектурные решения. Формат: один файл = одно решение.

Структура: Контекст (проблема) → Решение → Последствия → Альтернативы

Пример: docs/adr/001-migration-to-microservices.md

Как C4 и ADR работают вместе:

ADR отвечает: «Почему мы выбрали микросервисы?»

C4 показывает: «Как это выглядит в реальности»

Линкуйте C4 диаграммы в ADR:

# ADR-003: Переход на микросервисную архитектуру
 
## Контекст
 
См. текущую архитектуру: [C4 Level 2](../c4/02-containers.png)
 
## Решение
 
Выделяем отдельные сервисы по доменам...

C4 + Domain-Driven Design

DDD: Bounded Contexts, Aggregates, Entities

C4 Level 2: Bounded Context = Container

C4 Level 3: Aggregates и Domain Services = Components

C4 + Kubernetes

C4 Containers ≈ Kubernetes Deployments

Можно генерировать Level 2 из K8s манифестов:

# Псевдокод
deployments = kubectl.get_deployments()
services = kubectl.get_services()
c4_containers = map_k8s_to_c4(deployments, services)
generate_diagram(c4_containers)

C4 + Customer Journey Map (CJM)

Это мой любимый симбиоз — когда user experience встречается с технической архитектурой. CJM и C4 решают разные задачи, но вместе дают полную картину системы.

Что такое CJM (кратко)

Customer Journey Map — карта пути клиента, которая показывает:

• Этапы взаимодействия пользователя с продуктом
• Touchpoints (точки контакта) на каждом этапе
• Эмоции, боли, триггеры пользователя
• Каналы коммуникации (веб, мобилка, email, звонок)

Как CJM и C4 дополняют друг друга

Связка CJM → C4:

1. CJM Stage → C4 Context

   • Этап в CJM (например, "Регистрация") → Actor в C4 Context + его взаимодействие с системой

2. CJM Touchpoint → C4 Container

   • Touchpoint "Мобильное приложение" → Container "Mobile App [React Native]"
   • Touchpoint "Email-уведомление" → Container "Notification Service [Node.js]"

3. CJM Action → C4 Component/Sequence

   • Действие пользователя "Оплата курса" → Component Diagram показывает PaymentGateway, EnrollmentManager, Bank Integration

4. CJM Pain Point → Архитектурное решение

   • Боль: "Долго грузится видео" → Решение: добавляем CDN + Adaptive Streaming (видно на C4 Level 2)

Практический процесс: от CJM к C4

Этап 1: Создаём CJM

Пользователь → Поиск курса → Просмотр → Регистрация → Оплата → Обучение → Получение сертификата
                  ↓             ↓          ↓             ↓         ↓              ↓
              Touchpoints:   Web App    Web App      Web App    Mobile          Email
                                                                + Email

Этап 2: Маппим на C4 Context

Этап 3: Декомпозируем Touchpoints в Containers

Каждый touchpoint из CJM становится Container'ом или группой Container'ов:

Детальная матрица соответствия: CJM → C4 → Метрики

Это шаблон, который я использую на воркшопах. Для каждого критичного этапа CJM заполняем:

Как использовать матрицу:

1. На воркшопе CJM + Архитектура (3 часа):

   • Заполняете CJM этапы и боли вместе с UX/Product (1 час)
   • Архитектор предлагает технические решения (1 час)
   • Команда договаривается о метриках и приоритетах (1 час)

2. В спринт-планировании:

   • Берёте строку из матрицы со статусом 🔴 Planned
   • Разбиваете на user stories
   • После релиза проверяете метрики успеха

3. На ретро:

   • Смотрите, достигли ли метрик успеха
   • Если нет — архитектурное решение не сработало, нужно пересмотреть

4. Для стейкхолдеров:

   • Одна таблица показывает связь UX → Tech → Business Value
   • CTO видит архитектуру, CPO видит impact на пользователей, CEO видит метрики

Этап 4: Выявляем архитектурные требования из CJM

Боли и эмоции пользователей → требования к архитектуре:

## CJM: Этап "Просмотр видео урока"
 
**Боли:**
 
- ❌ Медленная загрузка видео (frustration)
- ❌ Видео обрывается на плохом интернете
- ❌ Нет возможности смотреть оффлайн
 
**Архитектурные решения (в C4):**
 
- ✅ CDN для статики (Cloudflare)
- ✅ Adaptive bitrate streaming (HLS/DASH)
- ✅ Кэширование в мобильном приложении
- ✅ Progressive download для offline-режима
 
**C4 Level 2 отражает:**
 
- Container "Video CDN [Cloudflare Stream]"
- Container "Mobile App" с локальным кэшем
- Container "Video Service [Go]" для обработки стриминга

Пример: Полный цикл CJM → C4

CJM Сценарий: Студент записывается на платный курс

1. [Этап: Discovery] Студент ищет курс по Python
   → Touchpoint: Web App (поисковая страница)
   → Эмоция: Любопытство
   → Боль: Слишком много результатов, сложно выбрать

2. [Этап: Evaluation] Студент читает описание курса
   → Touchpoint: Web App (страница курса)
   → Эмоция: Интерес
   → Боль: Неясно, подходит ли по уровню

3. [Этап: Decision] Студент смотрит превью первого урока
   → Touchpoint: Web App + Video Player
   → Эмоция: Уверенность
   → Триггер: Бесплатный пробный урок

4. [Этап: Purchase] Студент оплачивает курс
   → Touchpoint: Web App + Платёжная форма
   → Эмоция: Тревога (безопасно ли?)
   → Боль: Долгий процесс оплаты

5. [Этап: Onboarding] Студент получает доступ к курсу
   → Touchpoint: Email + Mobile App Push
   → Эмоция: Радость
   → Ожидание: Сразу начать учиться

6. [Этап: Learning] Студент проходит уроки
   → Touchpoint: Mobile App (чаще всего)
   → Эмоция: Вовлечённость
   → Боль: Хочется учиться в метро (оффлайн)

7. [Этап: Completion] Студент получает сертификат
   → Touchpoint: Email + возможность скачать PDF
   → Эмоция: Гордость
   → Триггер: Поделиться в соцсетях

Mapping на C4 Architecture:

Level 1 (Context):

• Actor: Студент
• System: LMS (Система обучения)
• External: Bank (оплата), SMTP-шлюз (email), Firebase (push), LinkedIn (шаринг сертификатов)

Level 2 (Containers):

- Web Application [Next.js] ← этапы 1-4
- Mobile App [React Native] ← этапы 5-6
- API Gateway [Kong] ← все этапы
- Course Service [Python] ← этапы 2-3
- Payment Service [Node.js] ← этап 4
- Notification Service [Node.js] ← этапы 5, 7
- Certificate Service [Python] ← этап 7
- Video Service [Go] ← этапы 3, 6

Level 3 (Components для Payment Service — решаем боль этапа 4):

PaymentController
  ├─ BankGateway (интеграция с Bank)
  ├─ PaymentValidator (проверка данных)
  ├─ FraudDetector (защита от мошенничества ← решение боли "безопасно ли?")
  ├─ PaymentRepository (сохранение транзакций)
  └─ EnrollmentTrigger (автоматическая запись на курс после оплаты)

Архитектурные решения из CJM болей

Обратная связь: C4 → CJM

C4 диаграммы помогают валидировать CJM:

• Если в CJM touchpoint "Instant notification", а в C4 нет Notification Service → архитектура не поддерживает CJM
• Если CJM обещает "оффлайн-режим", а Mobile App в C4 без локального кэша → врём пользователям
• Если на этапе Payment в CJM критично "чувство безопасности", проверяем C4: есть ли SSL, токенизация карт, fraud detection?

Процесс синхронизации CJM и C4

На старте проекта:

1. Workshops с бизнесом и UX → рисуем CJM
2. Из CJM извлекаем touchpoints, actions, боли
3. Проектируем архитектуру (C4 Level 1-2) под эти требования
4. Валидируем: каждый touchpoint = Container или группа Containers

Во время разработки:

1. Новая фича → обновляем CJM (добавляем этап или touchpoint)
2. Проверяем C4: есть ли нужные Containers/Components?
3. Если нет → проектируем, если есть — переиспользуем

После запуска:

1. Аналитика показывает боли пользователей (drop-off на этапе оплаты)
2. Смотрим C4 Level 3 для Payment Service
3. Находим узкое место (например, медленный FraudDetector)
4. Оптимизируем архитектуру

Инструменты для связки CJM + C4

Для CJM:

• Miro — collaborative CJM workshops
• Smaply — специализированный инструмент для journey maps
• UXPressia — CJM + Personas

Для C4:

• Structurizr — как обычно
• C4-PlantUML — если хотите держать всё в коде

Связка:

• Держите CJM и C4 диаграммы в одном репо: /docs/ux/customer-journey.png и /docs/architecture/c4/
• Линкуйте в README: "Этап 'Оплата' в CJM реализован через Payment Service (см. C4 Level 3)"
• Используйте Notion/Confluence для связывания документов

Реальный кейс: CJM спас архитектуру от провала

Проект: Маркетплейс образовательных курсов, 200k пользователей

Проблема: Спроектировали архитектуру (C4 Level 1-2), начали разработку. Через 3 месяца — релиз. Конверсия в покупку: 0.5% (ожидали 5-7%).

Решение: Нарисовали CJM на основе реальных данных аналитики и интервью с пользователями.

Находки:

1. Этап "Оценка курса": 80% пользователей уходят, потому что нет социального доказательства (отзывов, рейтингов)
2. Этап "Оплата": Форма оплаты требует 12 полей — пользователи не заполняют

Архитектурные изменения (по C4):

1. Добавили Review Service (новый Container) → собираем и показываем отзывы
2. Рефакторинг Payment Service → интеграция с Stripe Checkout (2 поля вместо 12)
3. Добавили Recommendation Engine (новый Container) → персонализированные предложения курсов

Результат: Конверсия выросла до 6.2%. CJM показал, что строить, C4 показал, как строить.

Чек-лист: CJM + C4

• Для каждого этапа CJM есть соответствующие Actors в C4 Context
• Для каждого touchpoint в CJM есть Container в C4 Level 2
• Боли пользователей из CJM отражены в архитектурных решениях
• Критичные user actions имеют детальные Component Diagrams (Level 3)
• После изменения CJM обновляется C4 (и наоборот)
• CJM и C4 живут в одном репо и линкуются друг на друга

Продвинутые техники

Техника 1: Цветовое кодирование по статусу

🟢 Зелёный — production-ready
🟡 Жёлтый — в разработке
🔴 Красный — планируется к удалению
⚪ Серый — legacy, не трогаем

Техника 2: Deployment диаграммы (C4 расширение)

Показывают физическое размещение:

• На каких серверах/облаках работает
• Load Balancers, CDN
• Зоны доступности (Availability Zones)

Техника 3: Динамические диаграммы (C4 расширение)

Показывают последовательность взаимодействий (как UML Sequence):

User -> Web App: Открывает страницу курса
Web App -> API Gateway: GET /courses/123
API Gateway -> Auth Service: Проверяет токен
Auth Service -> API Gateway: Токен валиден
API Gateway -> Course Service: GET /courses/123
Course Service -> PostgreSQL: SELECT * FROM courses...
PostgreSQL -> Course Service: Данные курса
Course Service -> S3: Генерация presigned URL для видео
Course Service -> API Gateway: 200 OK + данные
API Gateway -> Web App: JSON response
Web App -> User: Рендер страницы

Мои главные ошибки с C4 (и как их избежать)

За 6 лет использования C4 я наступил на все возможные грабли. Вот самые болезненные.

Ошибка #1: Документация вместо коммуникации (2019)

Что случилось: Первый проект с C4. Потратил 3 недели на детальные диаграммы Level 1-4 для всех 15 сервисов. Красиво, правильно, в Structurizr DSL. Презентовал команде — все кивали. Через 2 месяца проверил: никто не открывал диаграммы ни разу.

Почему провалилось:

• Делал один, без команды
• Диаграммы "для галочки", не для решения проблем
• Не встроил в процесс (код-ревью, онбординг, планирование)

Что изменил:

• Теперь рисую диаграммы вместе с командой на воркшопах
• Обновляем в PR, обсуждаем на ревью
• Используем на каждом онбординге новичка
• Правило: диаграмма должна отвечать на конкретный вопрос команды, а не быть "правильной"

Ошибка #2: Перфекционизм вместо прагматизма (2020)

Что случилось: Проект на React + Node.js + PostgreSQL. Архитектор (я) требовал идеального соответствия C4-нотации. Спорил с командой:

• "Это не Container, это Component!"
• "Redis нужно показать отдельным контейнером!"
• "Где протокол на этой стрелке?"

Pull Request'ы задерживались. Разработчики начали ненавидеть C4. Скорость упала на 30%.

Почему провалилось:

• Я был C4-фундаменталистом
• Нотация стала важнее пользы
• Не договорились о "достаточном качестве"

Что изменил:

• Правило: если диаграмма не помогает принять решение — она не нужна
• Level 1-2 обязательны, Level 3 — только для сложных частей
• Цвет стрелки и размер шрифта — не важны
• Важно: понятность, актуальность, полезность

Ошибка #3: Игнорирование legacy-кода (2021)

Что случилось: Банковский проект, 70% кода — legacy монолит на Java (2010 года), 30% — новые микросервисы. Я нарисовал красивые C4 диаграммы для новых сервисов, про монолит написал: "Legacy System [Java]" одним квадратом.

Через месяц команда спросила: "А как монолит общается с новыми сервисами? Где это видно?" Диаграммы не отражали реальность.

Почему провалилось:

• Хотел показать "красивую" архитектуру, а не реальную
• Игнорировал 70% системы, потому что она "некрасивая"
• Не смог использовать диаграммы для планирования миграции

Что изменил:

• Честно показываю всю систему, включая legacy
• Для монолита делаю Level 2: показываю хотя бы крупные модули внутри
• Использую цветовое кодирование: зелёный (новое), серый (legacy), жёлтый (в миграции)
• Диаграммы показывают текущее состояние + target state через 6-12 месяцев

Ошибка #4: Забыл про людей (2022)

Что случилось: E-commerce проект, 25 разработчиков. Нарисовал C4 Level 2 с 18 микросервисами. Технически правильно. Но не показал ownership: кто за какой сервис отвечает.

Через 2 недели баг в Payment Service. Все смотрят на диаграмму: "Payment Service — ок, а кто это фиксит?" 30 минут выясняли, чья это команда.

Почему провалилось:

• Показал технологии, но не людей
• C4 Level 2 не отвечал на вопрос "кто отвечает?"
• Диаграмма не помогла решить реальную проблему

Что изменил:

• Добавляю ownership на диаграммы: Payment Service [Node.js] — Team Checkout
• Иногда делаю отдельный view "по командам": какие сервисы за какой командой
• Линкую из диаграмм в RACI-матрицу или Service Catalog

Ошибка #5: Не обновлял после изменений (2023)

Что случилось: SaaS-платформа, активная разработка. Нарисовали C4 Level 1-2 на старте проекта. Через 6 месяцев добавили 5 новых сервисов, переписали аутентификацию, мигрировали с MongoDB на PostgreSQL.

Диаграммы остались старыми. Новичок смотрит: "У нас MongoDB?" — "Нет, уже полгода PostgreSQL".

Почему провалилось:

• Не добавил обновление диаграмм в Definition of Done
• Не было автоматических напоминаний
• Диаграммы не версионировались вместе с кодом

Что изменил:

• Diagrams as Code в том же репозитории, что и код
• Pre-commit hook: "Изменения в services/ — проверь C4 диаграммы"
• PR template с чек-боксом: ☐ Обновлены архитектурные диаграммы (если нужно)
• Автогенерация Level 2 из Kubernetes манифестов где возможно

Что изменилось с 2019 по 2025

2019 (начало):

• ❌ C4 как документация
• ❌ Рисую один, для всех
• ❌ Детализация Level 1-4 для всего
• ❌ Идеальная нотация важнее пользы

2025 (сейчас):

• ✅ C4 как инструмент коммуникации и принятия решений
• ✅ Рисую вместе с командой на воркшопах
• ✅ Level 1-2 обязательно, Level 3 — прагматично
• ✅ Полезность важнее красоты, реальность важнее идеала

Главное изменение: Раньше я думал "как правильно нарисовать C4?", теперь думаю "какую проблему команды решает эта диаграмма?". Если ответа нет — не рисую.

Заключение: Архитектура как коммуникация

C4 Model — это не про красивые картинки. Это про снижение когнитивной нагрузки и эффективную коммуникацию в команде.

Что даёт C4 на практике

Принципы, которые работают

1. Начните с малого: Level 1 + Level 2 за пару часов
2. Diagrams as Code: версионируйте вместе с кодом
3. Живая документация: обновляйте инкрементально, не откладывайте
4. Аудитория решает: рисуйте для людей, а не для процесса
5. Автоматизация: генерируйте где возможно, рисуйте где нужно

Последнее слово

За 6 лет использования C4 я внедрил его в 20+ проектах — от стартапов до энтерпрайза. Это работает. Не идеально, не везде, не всегда. Но это лучший баланс между «ничего нет» и «UML-монстр на 500 страниц».

C4 не решит проблему плохой архитектуры. Но он сделает хорошую архитектуру видимой, понятной и управляемой.

История изменений (Changelog)

Эта статья — живой документ. Я обновляю её по мере накопления опыта и появления новых инсайтов.

Версия 1.1 — 13 декабря 2025

• ✅ Добавлен TL;DR для разных ролей (разработчик, архитектор, CTO, PM/UX)
• ✅ Расширен раздел "Типовые грабли" (+5 новых антипаттернов)
• ✅ Добавлена сравнительная таблица: C4 vs ArchiMate vs UML vs IDEF-0 vs 4+1
• ✅ Добавлена детальная матрица CJM → C4 с метриками успеха
• ✅ Добавлен раздел ROI с реальными цифрами и финансовым расчётом
• ✅ Добавлен раздел "Мои главные ошибки с C4" (2019-2025)
• ✅ Добавлен быстрый старт "Если у вас только 1 час"
• ✅ Добавлен пошаговый план внедрения (неделя 1-2-3)
• ✅ Добавлен раздел про интеграцию C4 + Customer Journey Map
• ✅ Упомянут плагин C4-VARP для VS Code
• ✅ Усилен акцент на "Архитектура как код": единственный способ поддерживать документацию актуальной
• ✅ Добавлено: почему Confluence/Wiki не работают для архитектурной документации
• ✅ Обновлено время чтения: 15 мин → 35-40 мин

Версия 1.0 — 12 декабря 2025

• Первая публикация статьи
• 4 уровня C4 с подробными примерами
• Практические принципы применения
• Реальные кейсы и инструменты
• Интеграция с Event Storming, ADR, DDD, Kubernetes

Планируется в следующих версиях:

• Видео-примеры создания диаграмм
• Шаблоны для Miro/Figma
• Готовые Structurizr DSL примеры для типовых архитектур
• Раздел "C4 для High-load систем"
• Раздел "C4 для Legacy-систем"

Обратная связь: Нашли ошибку или хотите дополнить статью? Напишите мне: contact форма или Telegram

Дополнительные материалы

Официальные ресурсы:

• c4model.com — официальный сайт с примерами
• Structurizr — инструмент от автора C4
• C4 Model на GitHub — примеры DSL

Книги:

• "Software Architecture for Developers" — Simon Brown (автор C4)
• "Documenting Software Architectures" — Clements et al.

Связанные статьи на этом сайте:

• Feature-Sliced Design: архитектура фронтенда без хаоса
• Архитектура как гипотеза

Мои проекты с C4:

• Slot-Me — платформа бронирования встреч (вся архитектура документирована в C4)
• PassWave — даже для небольших проектов C4 даёт ясность