# Карта системы и AI-архитектор

Карта контейнеров, компонентов и решений проекта и разбор фич AI-архитектором.

Карта системы — это живая схема вашего продукта: из чего он состоит, как части связаны между собой и какие архитектурные решения на них действуют. Её собирает AI по документам проекта и обновляет после каждого выпуска. AI-архитектор использует карту, чтобы разобрать новую фичу ещё до начала работы: что она затронет, с какими решениями может столкнуться и о чём нужно спросить автора.

## Где в облаке

- Сайдбар «База знаний», вкладка «Система» (адрес `/app/<пространство>/system`).
- Вкладка «Архитектура» у каждой фичи.
- Блок «Архитектура» у релиза на его странице в «Релизах».

![Карта системы: уровень «Контекст» — роли, система и внешние системы](/docs/cloud/system-map.png)

## Как устроена карта

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

- **Контекст** — ваша система, роли пользователей и внешние системы;
- **Контейнеры** — крупные части: приложения, сервисы, хранилища;
- **Компоненты** — устройство одного контейнера;
- **Домен** — сущности предметной области, их ключевые поля, состояния и переходы.

Двойной клик по блоку проваливается на уровень ниже, хлебные крошки внизу возвращают обратно. Клик по блоку открывает карточку справа (на узком экране — шторку).

## Как собрать карту

1. Откройте «База знаний» → «Система». Если карты нет, на экране «Карты пока нет» нажмите «Собрать карту». Собирать и пересобирать могут владелец и админ.
2. Перед сборкой облако показывает оценку: примерное число токенов, остаток квоты встроенного AI и что останется после сборки. На своей модели сборка в квоту не входит. Если оценка больше остатка, подключите свою модель — см. [Встроенный AI и своя модель](/docs/cloud/ai-settings).
3. Подтвердите «Собрать карту». Сборка идёт в фоне, страницу можно закрыть: видны шаги «Контекст и контейнеры», «Компоненты по фичам», «Домен: сущности и состояния», «Привязка источников». Если сборка упала, уже собранное сохраняется, а «Повторить сборку» не создаёт дублей и не трогает ваши правки.

AI читает спеки, ADR, базовое описание проектов (артефакты `Project baseline`), брифы и принятые задачи журнала. Код репозитория он не читает. Элемент, который AI вывел только из истории задач без подтверждающего документа, помечен «по истории — проверьте».

## Обновление после выпуска

Когда агент записывает выпуск (`record_release`, см. [Выпуски](/docs/concepts/releases)), облако обновляет затронутые элементы карты. На странице это видно по статусу «Идёт обновление по выпуску» и подписи «Обновлено … после выпуска». Выпадающий список «Изменения» подсвечивает на карте, что поменялось в выбранном выпуске. Кнопка «Пересобрать» запускает полную пересборку вручную.

## Карточка элемента

В карточке три вкладки:

- **«Описание»** — технологии, ключевые поля и состояния сущности, входящие и исходящие связи, фичи и выпуски, где элемент менялся, и источники;
- **«Решения»** — действующие ADR, привязанные к элементу;
- **«История»** — версии элемента с пометкой, кто менял: AI при сборке, AI при выпуске или человек, и кнопка «Откатить».

Карту можно править руками: «Править» (название, описание, технологии, родитель, форма на диаграмме, поля, состояния, переходы), «Слить с…» и «Удалить». Править могут владелец, админ и участник; наблюдатель и тестировщик только смотрят. Исправленные поля закрепляются: следующая сборка не перезапишет их, а предложит новое значение в блоке «AI предлагает» с кнопками «Принять» и «Отклонить». Слитое и удалённое можно вернуть через «История версий». Перетаскивать блоки и рисовать стрелки нельзя, раскладку строит система.

## Решения (ADR) на карте

Вкладка «Решения» показывает, какие архитектурные решения действуют на элемент: «Действуют», «Предложено заменить», «Конфликты» и «Устаревшие». Новый ADR AI размечает по элементам автоматически и сверяет с действующими: предлагает заменить старое или фиксирует конфликт. Решение можно привязать и отвязать вручную («Привязать решение», «Убрать»). Для уже существующих решений есть кнопка «Разметить решения» (владелец и админ). Как создавать ADR — в разделе [База знаний и поиск](/docs/cloud/knowledge-search).

## AI-архитектор и вкладка «Архитектура» фичи

Разбор запускается, когда агент публикует бриф, когда меняется текст фичи или кнопкой «Пересобрать» (не чаще раза в 10 минут). Результат на вкладке «Архитектура»:

- **«Что затронет»** — компоненты и сущности карты и новые элементы, которые предполагаются; всё кликабельно и ведёт на карту;
- **«Действующие решения»** — ADR, которые касаются затронутого;
- **«Конфликт»** и **«Риски»**;
- **«Расхождения на приёмке»** — отступления от решений, найденные при [приёмке](/docs/concepts/acceptance);
- **«Вопросы архитектора»** — не больше трёх за разбор. Ответить можно здесь или reply в [Telegram](/docs/cloud/telegram-bot). Пока вопросы открыты, план фичи не строится.

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

## Для агентов

Агенты читают карту и разбор через MCP: `system_map` (уровень, элемент или поиск), `architecture_review` (разбор опубликованной фичи или черновика брифа), `architecture_check` (действующие решения затронутых элементов для приёмки) и `feature_questions` / `answer_question` для вопросов. Подробности — в [справочнике MCP](/docs/reference/mcp-tools). При приёмке расхождение с ADR попадает в вердикт строкой `architecture:` и затем в блок «Архитектура» у релиза на странице «Релизы». Там расхождение можно отправить в бэклог или закрыть кнопкой «Не расхождение».

## Что дальше

- [Фичи и доска](/docs/cloud/features-board)
- [Лента обновлений](/docs/cloud/changelog)