C4 Model: четыре масштаба одной системы

В 2019-м я три недели рисовал C4 на пятнадцать сервисов. Structurizr DSL, все четыре уровня, правильная нотация. Команде показал, все кивали. Через два месяца диаграммы не открыл никто.

Документ жил в Confluence как памятник прошлому. Новичок всё равно спрашивал: «а можно я у тебя спрошу?» Квадратики были либо слишком высоко, либо слишком подробно. Архитектуры в них не было.

C4 от Simon Brown держит четыре масштаба: Context, Containers, Components, Code. Как карта: город с самолёта, потом улица, потом планировка дома. С 2019-го я так описываю почти все проекты. Не потому что нотация священна. Потому что иначе разговор про систему скатывается в «у нас микросервисы» и тишину.

Ниже: что это такое, как я рисую, где облажался.

Если есть час

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): [ссылка на диаграмму]

Чего не делать

PowerPoint, draw.io, Confluence. Диаграмму нельзя положить в тот же коммит, что и код. Через неделю она врёт. Mermaid, PlantUML, Structurizr DSL живут в Git рядом с сервисом. Если диаграммы нет в том же репозитории, её уже можно не открывать.

Отдельная папка «для галочки» тоже не работает. Команда даже не знает, что файлы есть. Кладу в /docs/architecture/, первую ссылку ставлю в README.md, показываю на онбординге, правя в том же PR, что и код.

Level 3 и 4 на старте для всего подряд я уже рисовал. Детали сгнили, доверие кончилось. Сначала Level 1 и 2. Level 3 только там, где без него уже врут.

Четыре уровня

C4 это Context, Containers, Components, Code. Четыре масштаба одной системы.

• Level 1, Context. Вид с самолёта: система, люди вокруг неё, чужие сервисы.
• Level 2, Containers. Вид города: какие крупные части запускаются отдельно.
• Level 3, Components. Вид улицы: из чего состоит одна часть.
• Level 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 библиотек
• Критичная бизнес-логика с неочевидными связями

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

Как я это держу живым

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 проверял соответствие диаграмм реальности

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

Что изменилось в цифрах

Для 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

Когда не рисую

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

• Лендинги, простые 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

Четыре недели, если команда ещё без схемы

Полноценное внедрение для команды 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: Рендер страницы

Где я облажался

За шесть лет наступил на все эти грабли сам.

Ошибка #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 не чинит плохую архитектуру. Он делает систему видимой в одном масштабе за раз. Если диаграмма не отвечает на вопрос команды, я её не рисую.

За шесть лет это было около двадцати проектов. Не везде прижилось. Там, где диаграмма жила в том же PR, что и код, новичок переставал спрашивать «а как тут всё работает?» на третьей неделе.

Один квадрат, люди вокруг, чужие системы. Это уже Level 1. Остальное появляется, когда без него уже врут.

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

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

• Убран ролевой разбор «кому читать»
• Расширен раздел "Типовые грабли" (+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 даёт ясность