Как я перестал разрывать архитектуру на десяток документов — и сделал свой C4-редактор

Инструмент: C4 QuietGridLabs ^[1]. Можно открыть демо без авторизации: проект будет храниться локально в браузере.

Иногда архитектура «есть» — но пользоваться ею невозможно.

На доске лежит схема сервисов. В Confluence живёт описание. Где-то рядом — sequence-диаграмма, которую никто не открывал с прошлого года. ER-модель хранится в другом инструменте. А когда на ревью возникает простой вопрос «какой endpoint обслуживает этот путь?», команда начинает собирать ответ из памяти, догадок, выдумок, ссылок и исходников.

Я больше 15 лет работаю в ИТ, из них около десяти занимаюсь проектированием и системным дизайном. За это время перепробовал немало: Sparx, ArchiMate, Structurizr, Confluence, whiteboard-сервисы. Я не считаю их плохими — у каждого есть свой сценарий и своя аудитория. Но лично у меня постоянно оставалось ощущение разрыва: диаграмма была отдельно, документация отдельно, а живой контекст системы — в голове у людей.

В какой-то момент моими рабочими спасателями стали whiteboard и VS Code, а позже Cursor. В них можно быстро собрать мысль, оставить немного полезного творческого беспорядка и двигаться дальше. Но они не решали главную проблему: хотелось, чтобы система, её связи, сценарии и документация были одной навигационной моделью.

Так появился C4 QuietGridLabs. Это мой экспериментальный редактор, где C4-модель — это каркас проекта. К элементам можно прикреплять документацию, sequence-диаграммы, ER-диаграммы и описание API, а по связям — переходить от общего ландшафта к конкретным участникам взаимодействия.

В статье покажу это на небольшом примере интернет-банка путь, которым я сам хотел бы пользоваться при разборе незнакомой системы или же при проектировании новых систем.

Что можно сделать уже сейчас

• Моделировать систему на четырёх уровнях C4: System Context, Container, Component и Code.

• Создавать связи между элементами и подсвечивать их соседей.

• Проваливаться в дочерние уровни двойным кликом — почти как в директории.

• Вести Markdown-документацию прямо у элементов модели.

• Создавать sequence-диаграммы на PlantUML и вставлять их в документацию.

• Работать с ER-диаграммой для компонента базы данных.

• Описывать API endpoint: request, response и headers.

• Экспортировать весь проект в JSON или отдельный элемент в ZIP с документацией и PlantUML.

• Работать над облачными проектами совместно и передавать контекст в Cursor или Claude Code через MCP-сервер.

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

Начинаем с границы системы

Первый уровень C4 — системный контекст. Здесь важно не нарисовать всё на свете, а честно ответить на два вопроса: за что отвечает наша система и с кем она взаимодействует.

В примере я создаю Internet Banking System, внешние сервисы и пользовательские каналы.

У каждого элемента можно задать краткое описание, технологию и признак внешней системы.

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

У узла может быть собственная документация. Иконка на карточке показывает, что она уже существует.

Внутри — Markdown с предпросмотром. Я специально не пытался изобрести новый формат: Markdown знают многие, он удобно хранится и переносится. Для таблиц есть Insert Table, чтобы не тратить время на ручное выравнивание разметки.

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

Спускаемся к контейнерам

Двойной клик по системе открывает уровень контейнеров: SPA, API-приложение, PostgreSQL и мобильное приложение.

Небольшое, но важное уточнение: контейнер в C4 — не обязательно Docker-контейнер. Это развёртываемая или исполняемая часть системы: приложение, база данных, фронтенд или отдельный сервис.

У API Application видны иконки документации и sequence-диаграмм. Для меня это одна из ключевых идей сервиса: диаграмма сценария не должна быть «где-то в папке». Она принадлежит элементу, контекст которого объясняет.

Sequence-диаграммы строятся на PlantUML. Сначала через Add from C4 model добавляем участников текущего слоя, затем описываем сообщения между ними.

Ограничение на участников того же слоя намеренное. Оно помогает не смешивать абстракции на одной диаграмме. Для длинных сценариев можно сворачивать group и alt.

Если диаграмму привязали не к тому элементу, это можно исправить через Attach.

Диаграмму можно вставить в Markdown-документацию API-приложения. В итоге рядом с описанием сервиса лежит не ссылка на ещё один документ, а сам сценарий: что происходит, в каком порядке и между кем.

Когда база данных — не просто цилиндр

Если открыть контейнер PostgreSQL, попадаем в ER-редактор.

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

Для этого нажмите правой кнопкой по элементу и выберите Add → Documentation.

Идём по связи, а не по памяти

Самая интересная для меня часть начинается со связей.

Стрелка между SPA и API сообщает, что они взаимодействуют. Но во время ревью почти всегда нужен следующий вопрос: «а какие именно части API участвуют в этом вызове?» Раньше я обычно открывал несколько схем, искал endpoint, затем сервис и пытался не потерять исходный контекст.

В редакторе связи выбираем Edit Connection.

В Related Components связываем интеграцию с компонентами внутри контейнера.

После этого View related components → In API Application открывает компонентный уровень и подсвечивает участников выбранной связи.

Например, можно быстро пройти путь SPA → API → Auth Service и увидеть, где именно он раскладывается внутри приложения. Подсветка сбрасывается кнопкой Clear connection highlight.

На уровне Component описываются контроллеры, сервисы, адаптеры, API endpoint и другие части контейнера. API Endpoint — отдельный тип компонента: у него нет уровня кода, зато есть поля для request, response и HTTP-заголовков.

Если нужно дойти до код

Последний уровень C4 — Code. Например, двойной клик по Auth Service открывает объекты внутри компонента: классы, интерфейсы, функции и другие элементы реализации.

У объекта можно указать тип, язык и добавить фрагмент кода либо псевдокод.

Я не уверен, что любую систему нужно документировать до уровня классов. Во многих проектах достаточно первых двух или трёх уровней — и это нормально. Code-уровень я вижу как инструмент для сложных, критичных или особенно запутанных частей, а также для онбординга нового инженера.

Совместная работа без «у кого открыта последняя схема»

Без авторизации можно работать локально. Для облачных проектов и совместного редактирования нужен аккаунт.

• Получите временные учётные данные через почту, указанную в сервисе, и после первого входа смените пароль.

• Авторизуйтесь и создайте проект кнопкой с папкой в toolbar.

• На canvas откройте настройку доступа кнопкой Share.

• Выберите группу и добавьте её к проекту.

• После этого проект становится доступен участникам группы. В нижней панели показаны активные пользователи; по клику можно перейти к области canvas, где сейчас работает конкретный человек.

  

  Модель также можно забрать с собой:

  • экспорт всего проекта создаёт JSON с иерархией и связями;

  • экспорт отдельного элемента создаёт ZIP с дочерними элементами, связями, документацией и PlantUML.

  Это может быть резервной копией, входными данными для другой системы или контекстом для LLM-инструмента. Но секреты и чувствительные данные в такой контекст, конечно, передавать не стоит.

Мне нужна честная обратная связь

C4 QuietGridLabs — не попытка заменить все архитектурные практики и не обещание автоматически поддерживать документацию актуальной. Это инструмент, который я делаю для одной конкретной цели: уменьшить расстояние между схемой, объяснением и реальным разговором команды о системе.

Попробовать сервис можно на c4.quietgridlabs.com ^[1].

Буду особенно благодарен за предметную обратную связь.

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

Всем спасибо!