Каждый архитектор сталкивается с вечной дилеммой: как правильно документировать архитектуру, чтобы она была понятна людям и одновременно пригодна для автоматизации? Сегодня разберем три основных подхода и выясним, когда какой использовать.

Проблемы архитектурной документации

Современная документация архитектуры должна решать множество задач одновременно. Она должна быть понятна разработчикам, архитекторам и бизнесу, поддерживать версионирование, интегрироваться в CI/CD процессы и оставаться актуальной. Стартапы, в большинстве случаев, либо не имеют документацию по архитектуре, либо она в очень примитивном виде и не может быть использована другими специалистами. Когда становиться более зрелым очень часто случается так что документация не соответствует реальной архитектуре в продакшене, что приводит к задержкам при добавление новых фичей, проблемам безопасности и ограничениям масштабируемости.

Ключевые проблемы традиционных подходов:

• Быстро устаревание диаграмм

• Сложность синхронизации с кодом

• Отсутствие автоматизации

• Различные уровни детализации для разных систем, продуктов

• Сложность версионирования визуальных артефактов

Модель С4: Иерархия абстракций

Модель C4, созданная Саймоном Брауном, представляет собой простой подход к визуализации архитектуры программного обеспечения через четыре уровня абстракции.

Уровень 1: Contex (Контекст)

Показывает систему в окружении пользователей и внешних систем. Это “вид с птичьего полета” — идеален для презентаций бизнесу и стейкхолдерам (и почему в русском языке нет слова близкому по значению, прошу прощения за англицизмы). Представьте что вы летите на самолете и видите под собой большой город из которого выходит много дорог к другими городам и поселкам, так вот большой город это система, а другие города и поселки это внешнее окружение, дороги же являются связями.

Уровень 2: Container (Контейнеры)

Разбивает систему на основные исполняемые компоненты: веб-приложения, API, базы данных, микросервисы. Подходит для архитекторов и техлидов. А теперь представьте что мы пересели на небольшой самолет и спустились ниже, мы летим над городом и видим, порт, центр, завод. Вот это и есть контейнеры т.е. то что можно ограничить и выделить определенные функции.

Уровень 3: Components (Компоненты)

Детализирует внутреннюю структуру контейнеров, показывая модули, сервисы, контроллеры. Необходим разработчикам для понимания внутренней архитектуры. Тут еще проще представить это в виде завода. Склад, здание цеха (производства), здание управления (офисы). Так завод превращается во вполне организованную и понятную структуру.

Уровень 4: Code (Код)

На этот уровень редко кто приходит, это поле деятельности для разработчиков. UML диаграммы классов, часто автогенерируемые из кода. В данные момент большинство IDE справляются с этой задачей, обычно в виде структур. Для упрощения понимания это склад изнутри, секции со стелажами, имея карту можно легко найти что необходимо.

Преимущества C4 модели

Простота и доступность: C4 не требует изучения сложных нотаций. Используются простые блоки и стрелки, что делает диаграммы понятными даже нетехническим специалистам.

Иерархическая структура: Возможность показать архитектуру на разных уровнях детализации позволяет удовлетворить потребности различных аудиторий — от CEO до разработчиков.

Широкая инструментальная поддержка: Поддерживается множеством инструментов — от Structurizr и PlantUML до Miro и Lucidchart. Самый популярный инструмент для работы Drawio.

Недостатки C4 модели

Ограниченная машиночитаемость: Визуальные диаграммы сложно автоматически валидировать, анализировать или генерировать из кода.

Проблемы с версионированием: Сложно отслеживать изменения в визуальных диаграммах через систему контроля версий.

Ручное поддержание актуальности: Требует постоянных усилий для синхронизации с реальным состоянием системы.

YAML: Архитектура как код

YAML (YAML Ain’t Markup Language) изначально создавался как человекочитаемый формат сериализации данных. В контексте документирования архитектуры YAML позволяет создавать Architecture as Code — подход, при котором архитектура описывается в текстовом формате и может быть обработана автоматически.

Структуризованное описание архитектуры

Современные инструменты, такие как Structurizr DSL, позволяют описывать C4 модели в YAML-подобном синтаксисе:

workspace:
  name: "Banking System"
  
model:
  people:
    - name: "Customer"
      description: "Bank customer"
  
  systems:
    - name: "Internet Banking"
      containers:
        - name: "Web Application"
          technology: "React"
        - name: "API Gateway"
          technology: "Kong"
        - name: "Database"
          technology: "PostgreSQL"

Преимущества YAML-подхода

Превосходная машиночитаемость: YAML файлы легко парсятся, валидируются и обрабатываются автоматически. Это открывает возможности для автоматической генерации диаграмм, валидации архитектурных правил и интеграции в CI/CD пайплайны.

Отличное версионирование: Текстовые файлы идеально подходят для Git — можно легко отслеживать изменения, делать code review архитектурных решений, использовать branching strategies.

Высокий уровень автоматизации: Возможность генерировать множественные представления из единого источника истины — C4 диаграммы, PlantUML, Mermaid, API документацию.

Интеграция с разработкой: YAML файлы можно хранить рядом с кодом, что повышает вероятность актуализации документации при изменениях в системе.

Недостатки YAML-подхода

Ограниченная визуальная наглядность: Текстовый формат не так интуитивно понятен, как диаграммы, особенно для нетехнических специалистов.

Порог входа: Требует изучения синтаксиса и понимания структуры данных, что может быть сложно для начинающих архитекторов.

Зависимость от инструментов: Для эффективного использования необходимы специализированные инструменты для визуализации и валидации.

Blocks & Lines: Классический подход

Традиционный подход “блоки и линии” представляет собой создание архитектурных диаграмм в графических редакторах (Visio, Draw.io, Lucidchart) без строгой методологии или стандартизации. Часто используется для набросков и оформления брейнштормов.

Характеристики подхода

Максимальная гибкость: Возможность создавать любые диаграммы в любом стиле без ограничений нотации.

Низкий порог входа: Не требует изучения специальных методологий — достаточно базовых навыков работы с графическими редакторами.

Визуальная выразительность: Полный контроль над внешним видом, возможность создания красивых презентационных материалов.

Проблемы традиционного подхода

Отсутствие стандартизации: Каждый архитектор использует собственную нотацию, что затрудняет понимание и поддержку диаграмм другими специалистами.

Сложности с версионированием: Бинарные файлы (Visio, Draw.io) плохо подходят для систем контроля версий.

Проблемы с масштабированием: Сложно поддерживать консистентность в больших проектах с множеством диаграмм.

Отсутствие автоматизации: Невозможность автоматической генерации, валидации или интеграции с другими инструментами разработки.

Переходы между подходами

Миграция с Blocks & Lines

Постепенный переход: Существующие диаграммы можно постепенно стандартизировать под C4 модель, а затем перевести в машиночитаемый формат.

Сохранение инвестиций: Визуальные элементы можно сохранить через экспорт в различные форматы представления.

C4 в YAML

Прямой переход: Большинство C4 диаграмм можно вручную перевести в Structurizr DSL, сохранив всю семантику.

Инструментальная поддержка: Некоторые инструменты поддерживают импорт C4 диаграмм в текстовые форматы.

YAML = множественным представлениям

Из YAML можно автоматически генерировать:

• C4 диаграммы различных уровней

• PlantUML схемы

• Mermaid диаграммы

• API документацию

• Архитектурные тесты

Современные инструменты поддерживают экспорт в PNG, SVG, PDF для включения в презентации и документы.

Будущие тенденции

AI-Enhanced документирование

Искусственный интеллект уже начинает влиять на архитектурную документацию.

• Автоматическое извлечение архитектуры из кода

• Генерация диаграмм по текстовым описаниям

• Валидация согласованности между документацией и реализацией

• Автоматическое обновление документации при изменениях в коде

Живая архитектура

Концепция “живой архитектуры” предполагает:

• Реальное время синхронизации между кодом и документацией

• Автоматическое обнаружение архитектурных паттернов

• Непрерывная валидация архитектурных правил

• Интерактивные диаграммы с drill-down возможностями

Практический выбор в 2025 году

Выбор подхода к документированию архитектуры зависит от контекста, но общие тренды указывают на гибридные решения:

Для большинства команд оптимальна стратегия:

• Машиночитаемая основа (YAML) как источник истины

• Автоматическая генерация визуальных представлений (C4, PlantUML)

• Интеграция в процессы разработки через CI/CD

• Множественные форматы для разных аудиторий

Ключевые принципы успешной архитектурной документации:

• Близость к коду повышает актуальность

• Автоматизация снижает overhead и ошибки

• Визуализация улучшает понимание

• Стандартизация обеспечивает консистентность

• Версионирование сохраняет историю решений

А как же Archimate и TOGAF?

Хороший вопрос и на него сложно ответить однозначно. Возможно я посвящу этому отдельную статью в будущем. Но если кратко, TOGAF это фреймворк для управления проектами. В России в полном объеме он так и не прижился. ArchMate это визуальное представление части этих процессов. Многие компании пытаются использовать это как стандарт, но с моей точки зрения практической пользы в этом мало.

Подписывайтесь на канал для получения актуальных инсайтов об архитектуре, AI и современных технологиях разработки!