Содержание
Короткий ответ такой: если нужна схема архитектуры, которую обсуждают и ревьюят как код, берите Structurizr и модель C4. Для интерактивной карты репозитория под онбординг и ревью есть CodeSee. Циклы и границы импортов в JS/TS закрывают Madge и dependency-cruiser. А если нужен граф, сгенерированный из кода, вместе с документацией, историей git и горячими точками, посмотрите на repowise.
| Инструмент | Что рисует | Откуда берёт данные | Свежесть | Статус |
|---|---|---|---|---|
| Structurizr | C4: контекст, контейнеры, компоненты, код | модель, которую пишете вы (DSL) | обновляете руками | активно развивается |
| CodeSee | интерактивные карты репозитория, карты PR | анализ репозитория | генерируется | с мая 2024 года принадлежит GitKraken, Maps доступны |
| Sourcetrail | навигация по символам и графу | локальная индексация | генерируется | архивирован в декабре 2021 года |
| Madge | граф модулей JS/TS, циклы | импорты | генерируется | активен |
| dependency-cruiser | граф и правила импортов | импорты + конфиг правил | генерируется, проверяется в CI | активен |
| repowise | граф от пакетов до символов, слои, C4-представление | AST + история git | генерируется при каждой индексации | активен, AGPL-3.0 |
Scroll the table sideways to see every column.
Вопрос, на который отвечает картинка
Визуализация полезна, когда отвечает на конкретный вопрос. Обычно таких вопросов три:
- «Как устроена система в целом?» Нужна схема для людей: какие сервисы, какие хранилища, кто кого вызывает. Для этого есть C4 и Structurizr.
- «Что затронет мой PR?» Нужна карта, сгенерированная из кода, в масштабе изменения. Для этого подходят CodeSee, графы зависимостей и страницы с радиусом влияния изменения (blast radius).
- «Где здесь риск?» Нужна картинка с историей: какие файлы часто меняются, кто ими владеет, где циклы. Для этого нужны графы с наложенной историей git.
Чаще всего в инструментах визуализации разочаровываются, когда пытаются ответить на третий вопрос инструментом для первого. Красивая C4-диаграмма не скажет, какой файл чинили сорок раз за квартал.
Критерии выбора
Свежесть. Схема, которую нельзя пересобрать из репозитория, через полгода превращается в картинку на стене. Иногда это нормально, потому что замысел бывает важнее текущего состояния. Тогда такую схему стоит читать как документ о замысле, по которому текущий код уже не проверить.
Уровни масштаба. Нужно уметь переходить от системы к пакету, от пакета к файлу, от файла к функции. В C4 это четыре уровня: контекст, контейнеры, компоненты, код.
Направление и циклы. Граф без направления рёбер почти бесполезен. Граф, который не показывает циклы, пропускает первый признак расползания архитектуры.
Читаемость на большом проекте. Граф на десять тысяч файлов без группировки превращается в клубок, поэтому нужны слои, модули и фильтры.
Связь с повседневной работой. Если инструмент живёт только в отдельном веб-приложении, его откроют на онбординге и забудут. Лучше, когда картинка доступна из CLI, CI, IDE или прямо в агенте через MCP.
Structurizr
Structurizr считается эталонным инструментом для C4. Модель описывается на DSL (подход «модели как код»), и из одной модели генерируется несколько представлений: ландшафт систем, контекст, контейнеры, компоненты, динамические и deployment-схемы. Модель лежит в репозитории, проходит ревью в PR и экспортируется в PlantUML, Mermaid и статический HTML.
Где хорош: архитектурная документация, обсуждение замысла, ревью архитектурных решений. Модель C4 и Structurizr давно прижились у архитекторов, в том числе в русскоязычном сообществе, и общий словарь «контейнер / компонент» сильно упрощает разговор.
Где заканчивается: модель пишете вы, и актуальна она ровно настолько, насколько её поддерживают. Сама из кода она не обновляется.
CodeSee
CodeSee строит интерактивные карты репозитория: папки и файлы со стрелками зависимостей, которые можно раскрывать и сворачивать, и отдельные карты для PR, показывающие, что затрагивает изменение. В мае 2024 года компанию купил GitKraken. На сайте codesee.io Maps по-прежнему доступны.
Где хорош: онбординг и ревью PR, когда нужно быстро увидеть форму изменения.
Где заканчивается: всё построено вокруг их собственного приложения. Теперь, когда CodeSee принадлежит GitKraken, стоит заранее выяснить, как продукт будет развиваться дальше.
Sourcetrail
Sourcetrail был одним из лучших локальных инструментов навигации по коду: переход от символа к символу с графом связей рядом. Проект закрыли в 2021 году, репозиторий архивирован 14 декабря 2021 года, есть форки сообщества. Я упоминаю его как образец удобства: хорошая карта кода разворачивается постепенно, от одного файла наружу, и при этом не теряет контекст.
Madge и dependency-cruiser
Это рабочие инструменты для командной строки. Madge строит граф модулей JS/TS, находит циклы (--circular) и выводит DOT или SVG через Graphviz. dependency-cruiser добавляет правила («ui не импортирует server», «никаких циклов») и отчёты в DOT, JSON и CSV, удобные для CI.
Где хороши: они быстрые и легко встраиваются в CI.
Где заканчиваются: только JS/TS, только уровень модулей, без истории и документации.
Как выглядит сгенерированная архитектура на большом проекте
Ниже три проекта из нашего индекса.
deepseek-harness: 12 578 файлов, 898 685 строк, 11 модулей. Сырой граф на таком объёме не читается, поэтому узлы раскладываются по слоям:
| Слой | Узлов |
|---|---|
| Application | 4 828 |
| Config | 3 748 |
| Test | 2 568 |
| Docs & Tooling | 938 |
| Utility | 187 |
| API | 161 |
| Service | 81 |
| CLI | 28 |
| Data | 25 |
| UI | 14 |
Scroll the table sideways to see every column.
Уже из таблицы видно, что почти 3 750 узлов приходится на конфигурацию, а слой API тонкий. На схеме это сразу подсказывает, куда смотреть: сначала прикладной код и 161 узел слоя API, а конфиги и тесты можно свернуть.
Grafana: 18 146 файлов и 3 379 253 строки, 66 групп циклических зависимостей, например «Grafana Data» и «Grafana Ui Components». На таком масштабе полезнее всего возможность перейти от цикла к его файлам.
Keycloak: 10 414 файлов, 1 071 725 строк, 135 групп циклов. Для Java-проекта с SPI это нормально, но на схеме именно эти места показывают, где модульность держится на договорённостях, хотя структура кода её не обеспечивает.
Хороша ли архитектура, эти картинки не скажут. Число циклов и размер слоёв зависят от языка, возраста и того, как проект собирается.
Живая и статичная визуализация
| Тип | Сильная сторона | Слабая сторона | Когда брать |
|---|---|---|---|
| Рисованная схема (C4) | показывает замысел, удобна для обсуждения | устаревает | архитектурные документы, ревью решений |
| Сгенерированная карта | всегда соответствует коду | на большом проекте шумит | онбординг, исследование |
| Граф в CI | ловит нарушения автоматически | не для людей вне команды | охрана границ |
| Представление для агента (MCP) | доступно прямо в IDE и чате | зависит от качества инструментов | работа с ИИ-ассистентами |
Scroll the table sideways to see every column.
На практике нужно и то и другое: рисованная C4-схема для замысла и сгенерированный граф, чтобы проверить, соответствует ли ему код. Расхождение между ними само по себе полезный сигнал.
Где здесь repowise
repowise мы делали для третьего вопроса из начала статьи: где риск. Он строит граф по AST для 16 языков, раскладывает его по слоям и модулям, показывает C4-подобное представление и кладёт рядом сгенерированную документацию, историю git, владельцев, горячие точки и циклы. Те же данные доступны агенту через MCP. Structurizr он не заменяет, потому что замысел архитектуры по-прежнему описывает человек, зато с repowise проще проверить, совпадает ли замысел с кодом. Открытый код, AGPL-3.0:
pip install repowise && repowise init
Как выбрать
- Для архитектурного документа, который обсуждают и ревьюят, берите Structurizr.
- Для карты под онбординг и ревью PR подойдёт CodeSee (с учётом того, что теперь он часть GitKraken).
- Циклы и правила импортов в JS/TS закрывают Madge и dependency-cruiser.
- Граф из кода с историей, документацией и риском строит repowise.
Как мы считали
Размеры, слои и число групп циклов взяты из последнего индекса каждого репозитория в repowise: deepseek-harness от 28 сентября 2026, Grafana и Keycloak от 11 августа 2026. Слоями мы называем разбивку узлов графа знаний по ролям, а группами циклов называем сильно связные компоненты графа импортов между файлами. Статусы Sourcetrail и CodeSee я проверил по их репозиториям и сайтам. Всё проверено 6 октября 2026 года.
Посмотреть архитектуру своего репозитория: вставьте ссылку на GitHub на repowise.dev.
Частые вопросы
Какой инструмент выбрать для визуализации архитектуры проекта?
Если нужна схема для людей, то Structurizr и модель C4: описываете систему на DSL и получаете согласованные диаграммы разных уровней. Если нужна картина, сгенерированная из кода, подойдут графы зависимостей и карты вроде CodeSee или repowise.
Как сделать C4-диаграммы из кода автоматически?
Полностью автоматически хорошую C4-схему не получить: уровни контекста и контейнеров отражают замысел, которого нет в коде. Нижние уровни (компоненты и код) можно генерировать из графа зависимостей, а верхние лучше держать в Structurizr.
Чем визуализировать граф зависимостей в JavaScript-проекте?
Madge подходит для быстрого графа и поиска циклов и выводит SVG через Graphviz. dependency-cruiser нужен, если требуются правила и проверка в CI.
Sourcetrail ещё поддерживается?
Нет, проект закрыт в 2021 году, и репозиторий архивирован. Существуют форки сообщества, но новой команде я бы не советовал начинать с них.
Помогает ли визуализация кода при онбординге?
Да, если картинка отвечает на вопросы новичка: где что лежит, как связаны модули, какие места опасно трогать. Для этого лучше всего работают интерактивные карты с переходом к файлам и сгенерированная документация рядом с графом.