deweb

Единый граф связей системы — от одной команды до всего предприятия

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

open sourceAGPL-3.0разворачивается в своём контуре
Как это устроено

Проблема

«Кого заденет это изменение?»

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

Оценка влияния — дни переписки и созвонов вместо запроса.

Инциденты после релиза — из-за потребителя, о котором никто не вспомнил.

Проектирование отстаёт — потому что начинается с археологии.

Где живёт знание о связях сейчас

Документацияописывает, как задумывалось, и устаревает с момента публикации
Код и конфигурацииу каждой команды свой репозиторий и свои соглашения
Телеметриязнает, как система работает на самом деле, но видна только эксплуатации
Головы людейсамый полный источник — пока человек не в отпуске и не уволился

Идея

Одна модель на всю систему: сценарии, функции, данные

deweb описывает систему гибкой доменной моделью и связывает всё в один граф. Какие типы сущностей бывают и как они могут быть связаны, задаёт доменная схема. Стартовая схема — три типа:

  • use_case — сценарии: бизнес-процессы и шаги пользователя.
  • function — экраны, BFF, методы API, задания и обработчики событий.
  • data — таблицы, события и прочие хранимые сущности.

Схема — файл YAML: новый тип сущности или связи вводится конфигурацией, без правки кода. Группы — пути вида taskmanager.task, вложенность выбирает команда.

USE_CASEFUNCTIONDATAtaskmanagertaskmanager.use_casestaskmanager.frontendtaskmanager.bfftaskmanager.tasktaskmanager.userusesusesСоздать задачуСоздать задачуИмпорт пользователейPOST /tasksPOST /users/validatePOST /tasksPOST /userstaskseventsusers
Приложение taskmanager в одном графе: сценарий, функции и данные — сущности своих типов, связанные по правилам схемы. Связь uses между сервисами task и user видна сразу: изменение POST /users затронет сервис task.

Откуда берутся данные

Граф собирается из того, что у команд уже есть

Документы deweb

работает

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

:deweb.base: function
:deweb.name: GET /payroll/v1/timesheets/{id}
:deweb.path: personnel.payroll.rest

*Логика*
. Отдаёт табель учёта времени с позициями.

*Исходящие связи*
// tag::deweb-links[]
* `@data: personnel.payroll.db [payroll_timesheets]`
* `@data: personnel.payroll.db [payroll_timesheets_history]`
// end::deweb-links[]

Пример в формате AsciiDoc. Даёт заявленные связи — как задумано.

Спецификации и код

работает

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

Телеметрия

в планах

Распределённые трассировки показывают, кто кого реально вызывает. Даёт фактические связи — как работает на самом деле.

Заявленное и фактическое сверяются между собой: связь без трафика и трафик без описания — самостоятельная находка.

Архитектура

Ядро продукта и утилиты под ваши источники

Данные собирают утилиты двух видов. Продуктовые входят в deweb и решают универсальные задачи. Проектные пишутся под источники компании. Все они выдают AST одного формата, а дальше путь общий: документы, ревью, загрузка через API.

сбор данных · утилиты разбирают источники в документы dewebпродукт dewebИСТОЧНИКИУТИЛИТЫДОКУМЕНТЫOpenAPIyamlPlantUML ERentity diagramГраф в jsonиз другой системыИсходники проектакод и конфигурациипродуктовые утилитыразбор OpenAPIразбор PlantUMLимпорт графа из jsonпроектные утилитыпоиск файловразбор кодаразбор конфигурацийASTjson · единый форматгенерация документовдокументы dewebрепозиторий или база знанийзагрузка в графревью и правкиPOST /v1/graph/versionfrontendReact · nginxbackendFastAPI · Celery · PostgreSQL · RedisграфNebulaGraphпоискElasticsearchAPIпишет, читаетищетlistenerнаблюдаемостьOpenTelemetry · агент на узлеPrometheus — метрикиTempo — трейсы, Loki — логиGrafana — дашбордыпродуктовая — переиспользуетсяпроектная — пишется под источник

Почему это масштабируется

Чем больше команд в графе, тем больше видит каждая

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

Одна команда

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

Несколько команд

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

Предприятие

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

Что работает сейчас

Сбор данных и поиск зависимостей

  • Сбор сущностей и связей утилитами: из спецификаций, кода и документов.
  • Поиск сущностей и групп по подстроке, фильтр по типу.
  • Карточка сущности: кто от неё зависит и от чего зависит она.
  • Версии графа: просмотр изменений до слияния и слияние в origin.
  • Экспорт группы в диаграмму C4 (PlantUML).
  • Ссылка на любой экран — находку можно переслать коллеге.

Нарушенные связи версии отмечаются при загрузке, и такую версию нельзя слить, пока их не исправят.

Экран поиска deweb: 85 совпадений по запросу «событи» — сценарии, функции и группы с путями и числом связей Экран поиска deweb: 85 совпадений по запросу «событи» — сценарии, функции и группы с путями и числом связей
Поиск по демо-графу: 100 000 сущностей, 16 660 групп, 164 295 связей.

Интерфейс · сущность

Кто зависит от этой сущности

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

Карточка функции GET /payroll/v1/timesheets/{id}: три входящие связи из экрана фронтенда и двух групп сервиса recruiting Карточка функции GET /payroll/v1/timesheets/{id}: три входящие связи из экрана фронтенда и двух групп сервиса recruiting

Интерфейс · группы

Группировка повторяет вашу структуру

Группа — это путь в документе, и вложенность выбирает команда. «Приложение → сервис → слой» — одна из удобных схем для микросервисной архитектуры, но не обязательная. В демо-графе рядом живут разные:

бэкенд
<app>.<service>.rest · db · jobs · consumers
фронтенд
<app>.frontend.<раздел>.<экран>.<блок>
сценарии
<app>.cases
сквозные
Сквозные сценарии — <тема>
Стартовый экран deweb: размер графа и строка поиска Стартовый экран deweb: размер графа и строка поиска
Стартовый экран показывает размер графа и ведёт в поиск.
Группа personnel: подгруппы frontend, cases и пять сервисов, отсортированные по числу связей Группа personnel: подгруппы frontend, cases и пять сервисов, отсортированные по числу связей
Приложение personnel: фронтенд, сценарии и сервисы на одном уровне, по числу связей.

Куда развивается

От поиска зависимостей к управлению изменениями

Видеть

  • Исследование состава сущностей и связей между ними — от приложения до таблицы. есть
  • Экспорт группы в C4. есть
  • Экспорт диаграмм последовательностей. скоро
  • Две модели графа: заявленная по документации и фактическая по телеметрии.
  • Diff графа между релизами.
  • Теги критичности сущностей.

Анализировать

  • Импакт-анализ изменяемых компонентов и функций.
  • Кратчайший путь для новой интеграции.
  • Трассировка сущностей на баги — история участка при проектировании изменения.
  • Владельцы сущностей и готовый список согласующих.

Защищать

  • Валидация нарушенных связей при обновлении фрагмента графа. есть
  • Отчёт о влиянии в merge request: какие потребители затронет изменение.
  • Подписка на сущность: уведомление потребителям о её изменении.

Проектировать с LLM

  • Цифровая модель приложений как контекст для LLM в анализе и проектировании.
  • Доступ ассистентов к графу через API и MCP.

Цифровая модель для LLM

В контекст попадает не вся документация, а связанный подграф

Модель не помнит систему целиком, а контекст ограничен. deweb отдаёт ассистенту ровно ту часть графа, которую затрагивает вопрос, — с типами сущностей и связей вместо пересказа в прозе.

БЕЗ МОДЕЛИС ЦИФРОВОЙ МОДЕЛЬЮ DEWEBДокументация, код, схемысотни страниц в прозеКонтекст LLMне помещается в контекстОтвет по неполным даннымважное вытеснено из контекстаВопрос об изменении«меняем POST /users»deweb: связанный подграфсущности, связи, типыКонтекст по делутолько то, что затронуто

Кому что даёт

Один граф — шесть разных ответов

ИТ-директор

  • Прозрачность ландшафта, не зависящая от памяти ключевых людей.
  • Меньше инцидентов после релиза из-за неучтённых зависимостей.
  • Открытый код: меньше рисков зависимости от вендора, продукт можно доработать под себя.

Архитектор

  • Карта связей, собранная из источников, а не нарисованная вручную.
  • Расхождение заявленной и фактической архитектуры.
  • AS-IS от приложения до таблицы для принятия решений.

Техлид команды

  • Риски интеграций видны при оценке задачи, а не посреди спринта.
  • Онбординг по графу вместо устных пересказов.
  • Критичные участки отмечены тегами.

Разработчик

  • Кто использует мой эндпоинт или таблицу — за секунды. есть
  • Нарушенные связи ловятся до слияния. есть
  • Ссылка на сущность вместо переписки.

Тестировщик

  • Объём регрессии из импакт-анализа, а не из опыта и осторожности.
  • Diff графа между релизами: что именно изменилось.
  • История багов по связанным сущностям.

Системный аналитик

  • Текущее состояние системы без археологии. есть
  • Кратчайший путь для новой интеграции.
  • LLM, работающий с моделью системы, а не с кипой документов.

Как внедряется

Начинается с одной команды и растёт вместе с охватом

  1. 01 · подключить источники

    Утилиты под источники

    Продуктовые утилиты — под универсальные задачи, проектные — под свои источники. На выходе документы deweb, которые загружаются в граф.

  2. 02 · описать сущности

    Документы по доменной модели

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

  3. 03 · расширять

    Следующие команды

    Каждая подключённая команда замыкает обрывы соседей. Телеметрия добавит фактический слой поверх заявленного.

Развёртывание

Docker Compose: стенд целиком одной командой или по ролям на разных машинах — данные, приложение, наблюдаемость. Данные остаются в контуре компании.

Наблюдаемость из коробки

Трейсы, метрики и логи через OpenTelemetry, готовые дашборды Grafana: сам инструмент сразу наблюдаем.

Лицензия и стек

AGPL-3.0: используйте и дорабатывайте внутри компании свободно

  • Без ограничений по числу пользователей и без платы за лицензии.
  • Под свои процессы: типы сущностей, группировку, интерфейс, интеграции.
  • Проектные утилиты и доменная схема — ваши программы и данные.
  • Граф и документы остаются в контуре компании.

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

Стек и лицензии компонентов

компонентрольлицензия
dewebAPI, задания, интерфейсAGPL-3.0
NebulaGraphграфApache 2.0
Elasticsearch 7.17поиск по подстрокеElastic License 2.0
PostgreSQLзадания, версии, пользователиPostgreSQL
Redis 7.4очередь заданийRSALv2 или SSPL
nginxотдаёт интерфейсBSD-2-Clause
Prometheus, OTelметрики, сбор телеметрииApache 2.0
Grafana, Loki, Tempoдашборды, логи, трейсыAGPL-3.0

Сторонние сервисы скачиваются образами при развёртывании. deweb работает с ними по сети и их код не включает.

Следующий шаг

Что нужно для пилота

Команды и источники

  • Одна-две команды со смежными сервисами.
  • Доступ к их спецификациям: OpenAPI, PlantUML, репозитории с кодом.
  • Ответственный аналитик или архитектор: договорится о группировке и типах сущностей.

Инфраструктура в контуре

  • Стенд в контуре компании на Docker Compose.
  • Три ВМ по ролям — приложение, данные, наблюдаемость — или одна машина под всё.
  • Ресурсы подбираем под объём графа пилотных команд.

Что получим

  • Граф связей пилотных команд и поиск зависимостей по нему.
  • Первые межкомандные связи, видимые с обеих сторон.
  • Оценка эффекта: насколько быстрее анализ влияния изменений.