Состав системы

За что отвечает каждое приложение, какие есть внутренние пакеты и по каким каналам части платформы общаются между собой.

Frontend

Одностраничное приложение на Vue 3. Язык интерфейса только русский, файл переводов один.

В режиме разработки запросы к /api, /v1, /mcp, /cache и /healthz проксируются на API. В production приложение собирается и раздаётся самим API из каталога apps/api/ui-dist. Адрес API подставляется в момент выдачи страницы, поэтому один и тот же собранный интерфейс работает на любом домене.

API

Приложение apps/api. Единственная часть платформы, которая работает с базой данных.

Отвечает за:

• вход в систему, сессии входа, проверку прав;
• пользователей, роли, группы доступа;
• провайдеров и модели;
• каталог серверов MCP;
• агентов, правила, навыки;
• чаты, сообщения, запуски;
• файлы чатов и слой доступа к ним в стиле S3;
• журнал расхода;
• общие настройки платформы и лимиты;
• поиск и маскирование персональных данных;
• внешний OpenAI-совместимый API по адресу /v1;
• шлюз /mcp для внешних клиентов;
• проксирование ONLYOFFICE;
• раздачу интерфейса в production.

Runtime

Приложение apps/runtime. Оркестратор. К базе данных не обращается, всё нужное получает от API в теле задачи.

Наружу открывает только проверку состояния /healthz и четыре внутренних адреса /internal/*. Проверки прав на них нет.

Runtime нельзя открывать в интернет

Внутренние адреса Runtime не защищены авторизацией. Доступ к ним должен быть только из внутренней сети.

Отвечает за:

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

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

Внутренние пакеты

Пакет	Назначение
packages/shared	Общие типы и правила: контракты API, работа с правами, ограничения на файлы
packages/pii	Поиск и маскирование персональных данных
packages/guard	Проверка серверов MCP на подозрительное описание инструментов
packages/openai-compat	Типы и помощники для внешнего OpenAI-совместимого API
packages/domain	Пустая заготовка, содержимого нет

Каналы связи

Направление	Канал
Браузер к API	HTTPS, JSON, токен в заголовке Authorization
Браузер к API для ответа модели	Поток событий Server-Sent Events
API к Runtime	HTTP, ответ приходит потоком событий
Runtime к рабочим процессам	Обмен сообщениями между процессами Node.js
Рабочий процесс к модели	HTTPS к провайдеру
Рабочий процесс к серверу MCP	Транспорт MCP: stdio, Streamable HTTP или SSE
Сервер MCP к файлам чата	HTTP к API, доступ по временному ключу

Отдельного брокера сообщений в платформе нет. Очередь сообщений, которые не смогли начаться сразу, это таблица в базе данных, которую API просматривает по таймеру. Веб-сокеты для чата не используются, единственный такой канал нужен для ONLYOFFICE.