Вспомни, как обычно выглядит обсуждение архитектуры в среднестатистической продуктовой команде. Кто-то открывает онлайн-доску в Miro или Confluence, где нарисовано полтора десятка разноцветных прямоугольников с подписями «Сервис авторизации», «Шина данных» и «Бэкенд». Стрелочки направлены во все стороны сразу: одни показывают сетевые вызовы, другие — поток данных, третьи — зависимость по деплою. На вопрос «А что внутри сервиса авторизации?» тимлид вздыхает и говорит: «Там легаси на Express, половину переписали на Go, в схеме этого нет, надо смотреть в прод».
Через три месяца проект расширяется, появляются новые микросервисы, а старая картинка превращается в никому не нужный исторический памятник. Разработчики перестают смотреть в документацию, потому что она врет, а архитектурные решения принимаются «на коленке» прямо в ветках репозитория.
В начале 2000-х годов с этой проблемой пытались бороться с помощью стандарта UML (Unified Modeling Language), созданного консорциумом OMG. Но академическая сложность UML с его четырнадцатью типами диаграмм и строгими нотациями стрелочек задохнулась в эпоху Agile: команды просто не успевали обновлять тяжеловесные документы. Британский архитектор Саймон Браун (Simon Brown) предложил гениальный по своей простоте выход — модель C4, вдохновленную принципом масштабирования географических карт Google Maps.
А сегодня этот подход переживает второе рождение благодаря парадигме Architecture as Code (AaC) и языку Structurizr DSL. В серии глубоких исследований и лекций украинский инженер Тимур Шемсединов показал, как C4 решает принципиально новую задачу 2026 года: превращается в структурированную систему координат для ИИ-агентов (Claude, Cursor, Copilot, Windsurf), спасая команды от взрывного расхода токенов и архитектурных галлюцинаций.
Давай разберем эту многослойную механику от фундаментальных абстракций до практического кода и интеграции с нейросетями.
От бюрократии UML к масштабу Google Maps: истоки модели C4
Чтобы оценить элегантность C4, нужно на секунду вернуться в эпоху RUP (Rational Unified Process) конца 1990-х. Инженерная парадигма тех лет требовала «проектировать все до первой строчки кода». Аналитики месяцами рисовали комплекты UML: Use Case Diagrams, Sequence Diagrams, Component Diagrams, Deployment Diagrams.
Но когда индустрия перешла на двухнедельные спринты, continuous delivery и микросервисы, в UML вскрылись три системных порока:
- Чрезмерный академизм: Вместо ответа на вопрос «как доставить заказ» инженеры на ревью спорили о том, чем отличается ассоциация от агрегации и композиции на диаграмме классов.
- Отсутствие единой сквозной иерархии: В UML не было стандартного правила, как сопоставить общую бизнес-цель компании с конкретной базой данных. Диаграммы существовали изолированно, не образуя целостной системы.
- Непонятность для стейкхолдеров: Продакт-менеджер, глядя на UML Deployment Diagram с портами и артефактами, не понимал абсолютно ничего, а разработчик, глядя на диаграмму прецедентов, не видел стека технологий.
Саймон Браун обратил внимание на простую аналогию: как человек ориентируется в физическом мире? Ты открываешь Google Maps на смартфоне. На первом экране ты видишь континенты и страны. Это позволяет понять, где мы вообще находимся на глобусе. Приближаешь масштаб — появляются границы регионов, крупные города и магистрали. Еще зум — улицы, номера домов и повороты.
Модель C4 перенесла эту многоуровневую оптику в программную инженерию. Браун выделил четыре строгих уровня абстракции:
- Context (Системный контекст);
- Containers (Контейнеры);
- Components (Компоненты);
- Code (Код).
Каждый уровень отвечает на вопрос строго определенной аудитории и отсекает технический шум, ненужный на данном масштабе.
Четыре уровня абстракции C4: Context, Containers, Components, Code
Давай подробно препарируем каждый из четырех слоев модели.
1. Уровень 1: Системный контекст (System Context Diagram)
Это вид с высоты птичьего полета. В центре схемы располагается целевая программная система как единый черный ящик. Вокруг нее изображаются внешние сущности: пользователи (акторы, роли) и внешние системы, с которыми она взаимодействует (платежные шлюзы, CRM, почтовые провайдеры, государственные реестры).
Главное железное правило первого уровня: никаких технических деталей. Здесь строго запрещено писать «PostgreSQL», «Kafka», «gRPC», «Go» или «Linux». Только бизнес-роли и суть передаваемых данных: «Покупатель оформляет заказ», «Платежный сервис списывает средства». Эту диаграмму должен с первого взгляда понимать генеральный директор компании, инвестор и новый стажер в первый день онбординга.
2. Уровень 2: Контейнеры (Container Diagram)
Мы делаем первый шаг зума и «заглядываем внутрь» программной системы. И здесь важно не попасться в терминологическую ловушку: в модели C4 «контейнер» — это не Docker-контейнер и не Kubernetes Pod.
В понимании Саймона Брауна контейнер — это любая отдельно развертываемая или исполняемая единица программного обеспечения, которая хранит данные или исполняет код:
- Клиентское Single Page Application в браузере (React, Vite);
- Мобильное приложение (iOS / Android на Flutter);
- Серверный API-микросервис (Go, Node.js или Java);
- Реляционная база данных (PostgreSQL);
- Распределенный брокер сообщений (Apache Kafka);
- Объектное хранилище (MinIO / S3).
Диаграмма контейнеров — это любимая рабочая схема архитекторов, DevOps-инженеров и бэкендеров. Она показывает высокоуровневую топологию: какие сервисы существуют, за что отвечает каждый из них, на каких технологиях они построены (например, NestJS / TypeScript, PostgreSQL 16) и по каким протоколам они общаются (JSON/HTTPS, gRPC, Kafka Protocol).
3. Уровень 3: Компоненты (Component Diagram)
Следующий уровень приближения: мы берем один конкретный контейнер (например, API-сервис заказов) и раскрываем его внутреннее устройство на логические модули и компоненты: контроллеры, сервисы бизнес-логики, адаптеры внешних интеграций, репозитории доступа к данным.
Здесь кроется важнейшая рекомендация Брауна: не нужно рисовать диаграммы компонентов для каждого сервиса в компании. Если сервис представляет собой простой CRUD-модуль на 500 строк, моделировать его компоненты — пустая трата времени. Диаграмма компонентов создается только для архитектурно сложных, высоконагруженных или нетривиальных сервисов, где важно зафиксировать разделение слоев чистой архитектуры или паттерны отказоустойчивости.
4. Уровень 4: Код (Code Diagram)
Это предельный уровень детализации: диаграммы классов UML или сущностей Entity-Relationship (ER), отображающие интерфейсы, методы и зависимости в коде.
Современный инженерный консенсус предельно однозначен: уровень 4 категорически не нужно моделировать вручную. Классы и сигнатуры функций меняются в каждом коммите. Ручное ведение кода в архитектурных схемах моментально устаревает. Если диаграмма классов действительно необходима, она должна автоматически генерироваться из AST-дерева компилятором или средствами IDE.
Architecture as Code: единый источник правды на базе Structurizr DSL
Когда команды начинают внедрять C4, первой ошибкой обычно становится попытка рисовать эти диаграммы в графических редакторах вроде Draw.io, Lucidchart или Visio. Это тупиковый путь.
Представь: у тебя изменилось имя микросервиса или платежный шлюз перешел с REST на gRPC. Если схемы нарисованы вручную, архитектору приходится открывать диаграмму контекста, диаграмму контейнеров, три диаграммы компонентов и вручную перебивать текст в графических блоках. Человеческий фактор неизбежен: на одной схеме сервис назван по-новому, на другой остался старый протокол, на третьей забыли удалить стрелочку.
Парадигма Architecture as Code (AaC) проводит фундаментальную границу между моделью системы и ее визуальными представлениями (views).
Язык Structurizr DSL, разработанный Саймоном Брауном, предлагает декларативный текстовый синтаксис:
- В корне объявляется блок
workspace. - Внутри блока
modelединожды создаются все акторы, системы, контейнеры и связи между ними. - В блоке
viewsдекларируются диаграммы:systemContext,container,component. Командаinclude *сама выбирает нужные элементы из единой модели, а алгоритмautoLayoutавтоматически рассчитывает их экранные координаты.
Если ты меняешь технологию сервиса в блоке model, это изменение мгновенно и без твоего участия транслируется на все связанные диаграммы проекта.
Давай посмотрим на полноценный пример архитектурного манифеста интернет-магазина:
workspace "Маркетплейс" "Архитектурная модель сервисов электронной коммерции" {
model {
customer = person "Покупатель" "Пользователь интернет-магазина, выбирающий товары"
support = person "Оператор поддержки" "Сотрудник контакт-центра"
ecommerce = softwareSystem "Платформа покупок" "Обеспечивает витрину, обработку корзины и учет заказов" {
webApp = container "Web SPA" "Интерфейс в браузере клиента" "React, TypeScript"
mobileApp = container "Мобильное приложение" "Клиент для iOS и Android" "Flutter"
apiGateway = container "API Gateway" "Маршрутизация вызовов и аутентификация" "Envoy, Go"
orderService = container "Сервис заказов" "Бизнес-логика оформления и смены статусов" "Node.js, NestJS"
paymentService = container "Сервис платежей" "Взаимодействие с банками и фискализация" "Go, gRPC"
orderDb = container "База данных заказов" "Хранение заказов и истории транзакций" "PostgreSQL 16"
eventBus = container "Шина событий" "Асинхронная доставка доменных событий" "Apache Kafka"
# Связи контейнеров внутри системы
webApp -> apiGateway "Отправляет API-запросы" "JSON/HTTPS"
mobileApp -> apiGateway "Отправляет API-запросы" "JSON/HTTPS"
apiGateway -> orderService "Маршрутизирует вызовы заказов" "gRPC"
apiGateway -> paymentService "Маршрутизирует платежи" "gRPC"
orderService -> orderDb "Читает и пишет данные" "TCP/SQL"
orderService -> eventBus "Публикует событие OrderCreated" "Kafka Protocol"
paymentService -> eventBus "Подписан на события заказов" "Kafka Protocol"
}
bank = softwareSystem "Банковский шлюз" "Внешний процессинг банковских карт" "Внешняя система"
# Внешние взаимодействия
customer -> webApp "Просматривает каталог и покупает" "HTTPS"
customer -> mobileApp "Пользуется приложением" "HTTPS"
support -> webApp "Разбирает претензии по заказам" "HTTPS"
paymentService -> bank "Инициирует безналичное списание" "REST/HTTPS"
}
views {
systemContext ecommerce "SystemContext" "Диаграмма контекста платформы" {
include *
autoLayout lr
}
container ecommerce "Containers" "Топология контейнеров платформы" {
include *
autoLayout tb
}
styles {
element "Person" {
shape Person
background #08427b
color #ffffff
}
element "Software System" {
background #1168bd
color #ffffff
}
element "Container" {
background #438dd5
color #ffffff
}
element "Database" {
shape Cylinder
}
}
}
}
Этот файл хранится прямо в репозитории проекта по пути docs/architecture/workspace.dsl. Он проходит версионирование в Git, рецензируется через Pull Request, а любые изменения архитектуры видны в стандартном git diff.
Инструментальная экосистема: Structurizr Lite, экспорт в Mermaid и CI/CD
Текстовое описание в виде кода было бы бесполезным, если бы его нельзя было наглядно показать людям. Вокруг Structurizr DSL сформировалась зрелая экосистема утилит:
1. Structurizr Lite
Это компактный веб-сервер, распространяемый в виде Docker-контейнера. Он запускается на локальной машине разработчика буквально одной командой:
docker run -it --rm -p 8080:8080 -v $(pwd)/docs/architecture:/usr/local/structurizr structurizr/lite
Ты открываешь в браузере http://localhost:8080 и получаешь полноценную интерактивную карту системы. Можно приближать масштабы, кликать по контейнерам, подсвечивать связи и читать встроенную документацию. При сохранении файла workspace.dsl в IDE браузер мгновенно обновляет диаграммы на лету.
2. Structurizr CLI и мультивендорный экспорт
Если тебе нужно встроить схемы в проектную документацию на GitHub или в Confluence, консольная утилита structurizr-cli экспортирует единую модель в любой популярный графический синтаксис:
# Экспорт диаграмм в формат Mermaid для красивого рендеринга на GitHub
structurizr-cli export -w docs/architecture/workspace.dsl -f mermaid -o docs/images/
# Экспорт в C4-PlantUML для генерации растровых схем
structurizr-cli export -w docs/architecture/workspace.dsl -f plantuml -o docs/images/
Альтернативный вариант для команд, уже привыкших к PlantUML, — использование библиотеки C4-PlantUML, где схожая топология декларируется макросами:
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_WITH_LEGEND()
Person(customer, "Покупатель", "Клиент маркетплейса")
System_Boundary(c1, "Платформа покупок") {
Container(spa, "Web SPA", "React, TS", "Клиентский веб-интерфейс")
Container(gateway, "API Gateway", "Go / Envoy", "Точка входа и аутентификация")
Container(orders, "Сервис заказов", "NestJS", "Бизнес-логика заказов")
ContainerDb(db, "База заказов", "PostgreSQL", "Реляционное хранилище")
}
Rel(customer, spa, "Оформляет заказ", "HTTPS")
Rel(spa, gateway, "API-запросы", "JSON/HTTPS")
Rel(gateway, orders, "Маршрутизация", "gRPC")
Rel(orders, db, "Чтение / запись", "SQL")
@enduml
3. Архитектурный линтинг в CI/CD
Самое приятное в подходе Architecture as Code — возможность превратить архитектурную документацию в обязательную часть пайплайна непрерывной интеграции. В GitHub Actions или GitLab CI добавляется шаг валидации:
structurizr-cli validate -w docs/architecture/workspace.dsl
Если разработчик удалил сервис из кодовой базы, но забыл отразить это в архитектуре (или создал циклическую зависимость), билд завершается с ошибкой. Документация перестает быть мертвым грузом и становится живым инженерным контрактом.
Координатная сетка для ИИ-агентов: граф вместо слепого контекста
А теперь давай посмотрим на самое захватывающее применение моделей C4, о котором говорил Тимур Шемсединов. В 2026 году разработка программного обеспечения фундаментально трансформировалась: программисты больше не пишут весь код вручную, а делегируют реализацию фичей автономным ИИ-агентам (Claude 3.7 Sonnet, OpenAI Codex, Cursor, Windsurf).
Топологическая карта-схема Structurizr DSL, по которой ИИ-агент точно находит контейнеры orderService и orderDb в обход остального репозитория.
С ростом контекстных окон нейросетей до сотен тысяч и миллионов токенов у многих разработчиков возникла опасная иллюзия: «Зачем заморачиваться со структурированием? Давайте просто зальем в промпт весь монорепозиторий целиком — пусть нейросеть сама во всем разберется!»
На практике такой подход приводит к катастрофическим последствиям:
- Экономический тупик и задержка ответа: Прогон сотен тысяч токенов при каждом шаге агентного цикла сжигает десятки долларов на один запрос и заставляет разработчика ждать генерации по несколько минут.
- Архитектурные галлюцинации и размывание ответственности: Как мы подробно разбирали в материале о системах ограничений для AI-ассистентов, большие языковые модели не обладают встроенным пониманием архитектурных границ. Видя перед собой весь код без карты, агент начинает предлагать решения, нарушающие инкапсуляцию: обращается к чужой базе данных напрямую в обход сервисного API, дублирует вспомогательные функции или смешивает слои представления и доменной логики.
Архитектурный файл Structurizr DSL выступает для ИИ-агента топологической картой метрополитена.
Вместо сканирования гигабайтов исходников агент на первом шаге читает компактный DSL-файл размером всего 3–5 килобайт. За пару десятков миллисекунд модель получает полную ментальную модель проекта:
- Какие сервисы существуют и каковы их четкие зоны ответственности;
- Какие технологии и фреймворки используются в каждом контейнере;
- По каким протоколам и с какими гарантиями взаимодействуют узлы.
Получив пользовательскую задачу (например, «Добавить скидочные купоны в оформление покупки»), агент по графу C4 Containers мгновенно вычисляет, что изменения затрагивают исключительно контейнеры orderService и orderDb. Агент целенаправленно открывает только каталог apps/order-service, не трогая миллионы строк в остальных частях монорепозитория. Это снижает расход токенов на 80–90% и гарантирует, что ИИ не сломает архитектурные соглашения команды.
Границы применимости, антипаттерны и защита от архитектурного дрейфа
Как и любой мощный инженерный инструмент, модель C4 требует трезвого понимания границ применимости и защиты от типичных ошибок:
- Антипаттерн «Ручной микроменеджмент классов»: Попытка описывать компоненты до уровня мелких хелперов и DTO превращает DSL в неподъемную рутину. Держи модель на уровне крупных архитектурных модулей.
- Антипаттерн «Картинки ради картинок»: Если команда рисует C4 в онлайн-досках без использования DSL, теряются все преимущества версионирования, рендеринга и интеграции с ИИ.
- Проблема динамических процессов: Модель C4 великолепно передает статическую структуру систем, но слабо подходит для визуализации сложных временных распределенных саг, параллельных коллизий и гонок состояний. Для таких задач диаграммы последовательности (Sequence Diagrams) по-прежнему незаменимы и отлично дополняют C4 на уровне документации.
- Борьба с архитектурным дрейфом (Architecture Drift): Чтобы код не расходился с моделью со временем, передовые команды подключают тесты архитектурной целостности (ArchUnit в мире JVM или ts-arch в TypeScript). Тесты парсят фактические импорты в репозитории и сверяют их с задекларированными стрелочками в
workspace.dsl.
В результате Architecture as Code перестает быть скучной бюрократической повинностью. Это живой каркас, который позволяет людям и искусственному интеллекту говорить на одном понятном языке и строить надежные, масштабируемые цифровые системы.




