---
doc_id: REF-CK8S-0009
type: target-architecture
title: "kodex — целевая архитектура новой платформы"
status: active
owner_role: SA
created_at: 2026-04-21
updated_at: 2026-05-05
related_issues: [281, 282, 309, 376, 470, 488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave2"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Целевая архитектура новой платформы

## TL;DR
- Новая архитектура строится вокруг набора доменных сервисов-владельцев, а не вокруг одного `control-plane`.
- `web-console` и раздельные gateway-сервисы HTTP-входа остаются thin-edge и интерфейсным слоем, без владения доменной логикой и каноническим состоянием.
- Канонический первый набор сервисов-владельцев: `access-manager`, `project-catalog`, `provider-hub`, `package-hub`, `agent-manager`, `fleet-manager`, `runtime-manager`, `billing-hub`, `interaction-hub`, `operations-hub`.
- `worker` и `agent-runner` остаются исполнительными компонентами, но не владельцами доменной правды.
- `control-plane` в целевом состоянии должен исчезнуть как доменное ядро; допускается только временное существование как переходного thin shell без собственного доменного центра.

## 1. Архитектурные драйверы
Архитектура должна одновременно поддержать:
1. provider-first модель работы через `Issue`, `PR/MR`, комментарии, mentions и связи;
2. agent-manager как основной управляющий интерфейс продукта;
3. slot/runtime платформу с `code-only`, `full-env`, prewarmed slots и platform jobs;
4. MCP-контур для опасных операций, approvals и расширяемых инструментов;
5. настраиваемые внешние каналы взаимодействия и уведомлений, включая текст, голос и временные медиа-вложения;
6. встроенные и пользовательские роли с flow и шаблонами промптов, хранящимися в БД платформы и загружаемыми из установочных фикстур при bootstrap;
7. пакетную платформу для плагинов и пакетов руководящей документации;
8. многоорганизационную модель доступа, контур серверов и кластеров и биллинг;
9. постепенное вытеснение старого `control-plane` без сохранения его как новой стабильной формы.

## 2. Базовые архитектурные принципы

### 2.1. Один домен — один владелец истины
Каждый тип данных и каждый бизнес-процесс должны иметь один сервис-владелец.

### 2.2. Edge остаётся thin-edge
`services/external/*` и `services/staff/*` не становятся доменными сервисами.

### 2.3. Исполнители не владеют доменной правдой
`worker` и `agent-runner` выполняют задачи и reconciliations, но не определяют каноническое состояние бизнеса.

### 2.4. Provider-специфика изолируется
GitHub- и GitLab-особенности не должны расползаться по нескольким доменам. Для этого нужен отдельный owner-контур провайдера.

### 2.5. Runtime — отдельный тяжёлый operational контур
Слоты, build/deploy/cleanup jobs, реестр образов, Kubernetes orchestration и retention нельзя размазывать по агентной оркестрации.

### 2.6. Console и operator UX питаются от проекций чтения
Интерфейс не должен собирать бизнес-смысл напрямую из БД нескольких сервисов-владельцев и не должен превращать gateway-сервис в новый доменный центр.

### 2.7. Межсервисная синхронизация через доменные события
Таблицы разных сервисов-владельцев не связываются через `FOREIGN KEY`, cross-database join и каскадные операции. Даже если несколько сервисов физически используют одну PostgreSQL-инсталляцию или одну БД с разными схемами, их данные не образуют общую реляционную модель.

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

Если сервис-владелец меняет важное состояние, он публикует доменное событие через надёжный outbox. Другие сервисы получают событие через свой inbox или подписку, обрабатывают его идемпотентно и сами решают, что делать по своей бизнес-логике.

Пример: при удалении организации `access-manager` публикует событие удаления организации. `project-catalog`, `package-hub`, `billing-hub`, `runtime-manager`, `interaction-hub` и `operations-hub` не читают БД `access-manager`, а получают событие и применяют собственные правила: архивировать привязки, заблокировать новые операции, закрыть установки, остановить слоты, обновить витрины или запросить решение человека.

## 3. Целевая карта контейнеров и сервисов

### 3.1. Edge и UI
- `services/staff/web-console`
- `services/staff/staff-gateway`
- `services/external/integration-gateway`
- `services/external/user-gateway`
- `services/external/platform-mcp-server`

Общий `api-gateway` в целевой архитектуре не вводится. HTTP-поверхности разделяются по назначению:
- `staff-gateway` нужен рядом с `web-console`: перед реализацией пользовательского интерфейса или сразу после первого среза пользовательского интерфейса, когда известен набор OpenAPI-эндпоинтов для сотрудников и администраторов;
- `integration-gateway` нужен после базового `provider-hub`, когда известны webhook, обратные вызовы и входящие события от провайдеров и внешних интеграций;
- `user-gateway` можно сдвинуть на границу MVP или после MVP, потому что это HTTP-вход для внешних пользователей, а не обязательный контур внутренней staff-консоли.

### 3.2. Доменные сервисы-владельцы
- `access-manager`
- `project-catalog`
- `provider-hub`
- `package-hub`
- `agent-manager`
- `fleet-manager`
- `runtime-manager`
- `billing-hub`
- `interaction-hub`
- `operations-hub`

### 3.3. Исполнительные компоненты
- `services/jobs/worker`
- `services/jobs/agent-runner`

Для обоих компонентов действует жёсткое правило:
- они не ходят напрямую в чужие БД;
- они получают и изменяют доменное состояние только через контракты сервисов-владельцев;
- прямой SQL к authoritative данным других доменов считается архитектурным дефектом.

### 3.4. Хранилище
- PostgreSQL-контур как общий инфраструктурный кластер с database-per-service моделью

## 4. Роли сервисов в целевой архитектуре

### `access-manager`
Отвечает за:
- пользователей платформы;
- организации;
- группы;
- allowlist и вход;
- членство и права доступа;
- системные настройки;
- административный аудит.

### `project-catalog`
Отвечает за:
- проекты;
- репозитории;
- привязку источников проектной документации и project rules;
- проверку источников проектной документации для проектов с несколькими репозиториями;
- `services.yaml` и связанный config-контур;
- первичную настройку и preflight-проверки репозиториев;
- branch rules;
- release policies;
- привязки пакетов;
- placement policy проекта и репозитория.

### `provider-hub`
Отвечает за:
- provider accounts;
- webhook inbox, validation, deduplication и normalization;
- нативные сущности провайдера в нормализованном виде;
- зеркальные проекции, состояние дозаполнения и платформенные метаданные нативных сущностей;
- mentions, relationships и метаинформацию провайдера;
- `sync_cursor`, incremental reconciliation и `drift_status` по области синхронизации провайдера;
- приоритеты синхронизации горячих, тёплых и холодных сущностей;
- лимиты провайдера и ограничения внешних API;
- снимки лимитов провайдера от agent-run и будущий provider proxy для строгого соблюдения лимитного бюджета;
- выполнение provider-операций через интерфейсы.

Это отдельный сервис, потому что новая платформа уже не может позволить себе размазывать GitHub/GitLab semantics по `agent-manager`, runtime и UI одновременно.

### `package-hub`
Отвечает за:
- каталог пакетов;
- плагины и пакеты руководящей документации как записи каталога;
- каталог установленных пакетов;
- каталог доступных пакетов, полученный через клиентские подключения к магазинам пакетов;
- настройки подключения к авторскому магазину пакетов из приватного репозитория `github.com/codex-k8s/kodex-package-store`;
- пакет сайта и пользовательской документации платформы из приватного репозитория `github.com/codex-k8s/kodex-package-platform-site`;
- репозитории-источники пакетов и версии;
- статус верификации;
- состояние установки и импорта пакета;
- схемы секретов и описания возможностей пакета;
- ценовые данные и метаданные каталога.

Этот сервис не подменяет `provider-hub`: операции чтения и изменения репозиториев-источников пакетов идут через provider-контур.

`package-hub` не должен считать единственный публичный магазин пакетов встроенным источником истины. Магазин пакетов подключается как пакет, поэтому ядро платформы знает только клиентский контракт источника каталога, права, версии, установку и аудит. Бизнес-логика магазина остаётся внутри пакета магазина.

Source submodule пакетов объявляются в `.gitmodules` и checkout-ятся в `packages/**`. Метаданные установленных пакетов хранятся в БД платформы и могут предзаполняться из JSON-манифеста внутри репозитория пакета. Платные пакеты проходят через прокси платформы и проверку прав до checkout. Для downstream-репозиториев отдельный workflow удаляет магазин, сайт и необязательные пакеты, не предназначенные для конкретной установки.

### `agent-manager`
Отвечает за:
- разбор пользовательского намерения;
- выбор flow;
- каталог встроенных и пользовательских ролей;
- выбор `work`/`revise` шаблонов по профилю и правилам;
- запуск role-агентов;
- запуск параллельных ролей проверки и контроля после появления нужных артефактов;
- lifecycle run и session;
- acceptance machine;
- правила расписания и привязки триггеров;
- состояние исполнения релизной линии;
- handover и follow-up логику;
- остановку процесса при недостающих данных, лимитах или policy-блокировках.

`agent-manager` владеет каноническими flow, профилями ролей и шаблонами промптов в БД. Репозиторий платформы содержит только установочные фикстуры для первичной загрузки и обновления встроенных версий.

### `fleet-manager`
Отвечает за:
- реестр серверов и Kubernetes-кластеров;
- connectivity и health инфраструктурных контуров;
- политика размещения;
- привязку организаций, проектов, репозиториев и runtime-контуров к серверным и кластерным контурам;
- задел на multi-cluster и delegated clusters.

### `runtime-manager`
Отвечает за:
- slot lifecycle;
- reuse и prewarming;
- build/deploy/mirror jobs;
- cleanup/retention jobs;
- orchestration Kubernetes и реестра образов;
- технический статус среды;
- исполнение на уже выбранном контуре серверов и кластеров.

### `billing-hub`
Отвечает за:
- записи затрат;
- распределение затрат по организациям, проектам и другим контурам;
- основу для выставления счетов;
- использование внешних провайдеров и экономика пакетов;
- задел под платёжных провайдеров.

### `interaction-hub`
Отвечает за:
- диалоговые ветки пользователя с agent-manager;
- сообщения и краткие статус-отчёты, приходящие в пользовательские каналы;
- ссылки на временные медиа-вложения и их retention-контур;
- approvals;
- уведомления;
- delivery attempts;
- обработку обратных вызовов;
- внешний канал связи с человеком;
- subscriptions и маршрутизацию событий;
- шов для speech-to-text, text-to-speech и объектного хранилища временных медиафайлов.

### `operations-hub`
Отвечает за:
- операторские витрины состояния;
- ленту событий, очереди, блокировки и статусы;
- агрегированные представления для `web-console`;
- единый навигационный срез по run, `job`, задачам, ошибкам и ожиданиям действий человека.

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

`operations-hub` не становится владельцем первичных бизнес-данных. Он строит и отдаёт только проекции чтения.

### `platform-mcp-server`
Отвечает за:
- платформенную MCP-поверхность инструментов;
- авторизацию и policy-проверку MCP-вызовов;
- аудит MCP-действий;
- маршрутизацию вызовов к сервисам-владельцам;
- запуск approval и feedback-контуров там, где это требуется.

Это thin-edge сервис. Он не владеет доменной моделью и не хранит собственную каноническую правду.

## 5. Исполнительные компоненты

### `worker`
Общий фоновой исполнитель доменных задач и reconciliations.

Он может:
- подбирать ожидающие задачи;
- вызывать сервисы-владельцы;
- исполнять retry/expiry/reconciliation loops.

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

### `agent-runner`
Исполнитель агентных сессий и role-агентов в выделенном slot задачи.

Под slot здесь понимается:
- отдельный namespace задачи в текущей основной модели;
- в будущем, при необходимости, отдельный nested cluster как расширенный вариант slot.

Он может:
- выполнять инструкции;
- работать с кодом, проектной документацией, slot-окружением и MCP;
- возвращать результаты сервисам-владельцам.

Он не должен:
- определять канонический lifecycle run;
- ходить напрямую в чужие БД ради получения или записи доменного состояния;
- сам становиться источником истины для flows, approvals, provider state или jobs.

## 6. Ключевые потоки между сервисами

### 6.1. Входящий webhook или mention из GitHub/GitLab
1. `integration-gateway` валидирует входящее событие и маршрутизирует его.
2. `provider-hub` сохраняет сырое событие в `provider_event_inbox`, дедуплицирует delivery и ставит обработку в очередь.
3. `provider-hub` нормализует событие и обновляет provider state.
4. `agent-manager` получает нормализованный сигнал и решает, нужен ли run, follow-up или блокировка.
5. `runtime-manager` поднимает или переиспользует slot и platform jobs, если это требуется.
6. `interaction-hub` уведомляет человека, если нужен approval, feedback или операционное внимание.
7. `operations-hub` строит видимую оператору проекцию.

### 6.1.1. Потерянные webhook и сверка с провайдером
1. `provider-hub` ведёт `sync_cursor` по репозиторию, типу артефакта или другой области синхронизации провайдера.
2. `worker` исполняет incremental reconciliation с окном перекрытия и обновляет только изменённые проекции.
3. Горячие сущности получают более частый `next_check_at`; холодные проверки откладываются при дефиците лимитов провайдера.
4. Если обнаружен drift, `provider-hub` обновляет `drift_status`, пересчитывает проекцию и публикует доменное событие для потребителей.

### 6.2. Запуск задачи из UI/голоса
1. Пользователь работает через `web-console`, а `web-console` вызывает `staff-gateway` для операторских и административных HTTP-сценариев.
2. Быстрый экземпляр `agent-manager` работает через `platform-mcp-server` как основной инструментальный интерфейс.
3. `agent-manager` интерпретирует запрос и решает, создать ли `Issue`, продолжить ли существующую задачу или спросить уточнение.
4. Если требуется работа с провайдером, `platform-mcp-server` маршрутизирует вызов в `provider-hub`.
5. Если нужен состав workspace, `agent-manager` получает у `project-catalog` проверенный состав проектной документации и разрешённые репозитории задачи, а flow и шаблоны берёт из собственной БД.
6. Если требуется каталог пакетов, импорт guidance package или установка плагина, `platform-mcp-server` маршрутизирует вызов в `package-hub`.
7. Если требуется slot/runtime, `platform-mcp-server` маршрутизирует вызов в `fleet-manager` и `runtime-manager`.
8. `runtime-manager` готовит slot с кодом, проектной документацией и руководящими пакетами в согласованных локальных путях.
9. Если нужно уведомление, Human gate или внешний канал, используется `interaction-hub`.
10. Оператор видит агрегированное состояние через `operations-hub`.

### 6.3. Build/deploy/cleanup
1. `fleet-manager` определяет допустимый инфраструктурный контур.
2. `runtime-manager` создаёт и ведёт platform jobs.
3. `worker` или специализированные исполнители выполняют нужные действия.
4. Статус и краткий хвост лога возвращаются в контур-владелец `runtime-manager`.
5. `interaction-hub` и `operations-hub` распространяют это в уведомления и UI-проекции.

## 7. Что происходит со старым `control-plane`

### Целевое состояние
Старый `services/internal/control-plane` удаляется как единый доменный центр.

Его обязанности разъезжаются по новым сервисам:
- auth/admin/org/group -> `access-manager`
- project/repo config, branch rules, release policy -> `project-catalog`
- provider semantics/webhooks/лимиты провайдера -> `provider-hub`
- каталог пакетов и политика установки/импорта -> `package-hub`
- run/session/acceptance/flow/automation -> `agent-manager`
- реестр серверов и кластеров и размещение -> `fleet-manager`
- slots/build/deploy/cleanup -> `runtime-manager`
- billing and cost accounting -> `billing-hub`
- согласования/уведомления/обратные вызовы -> `interaction-hub`
- projections/operator views -> `operations-hub`

### Допустимое переходное состояние
На переходном этапе допустимо, что часть кода ещё физически живёт в старом каталоге, но только если:
- владение уже переписано в документации;
- старый слой не остаётся каноническим доменом;
- новый сервисный контур описан как целевой владелец;
- это рассматривается как временный migration shell, а не как финальная архитектура.

## 8. Что не нужно фиксировать преждевременно
В этой волне не нужно зацементировать:
- точную структуру таблиц и миграций;
- точные gRPC методы;
- точный формат watermark;
- точные event/outbox контракты, при том что сам принцип доменных событий и outbox/inbox уже обязателен;
- точный выбор механизма расширения внешних каналов.

Это пойдёт следующими волнами поверх уже зафиксированной service map.

## 9. Отложенные архитектурные заделы
Нужно уже сейчас держать в уме, но не выделять в отдельные сервисы-владельцы без необходимости:
- контур хранения знаний и жизненный цикл векторного индекса;
- расширенные governance-проекции поверх базовых операторских экранов;
- дополнительные реализации provider-интерфейсов помимо GitHub;
- специализированные фоновые исполнители по отдельным доменам, если общий `worker` станет узким местом.
