---
doc_id: REF-CK8S-0003
type: domain-map
title: "kodex — доменная карта новой платформы"
status: active
owner_role: SA
created_at: 2026-04-21
updated_at: 2026-04-25
related_issues: [470, 488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave0"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Доменная карта новой платформы

## Принцип
Платформа должна строиться не вокруг внутренних магических рабочих сущностей, а вокруг сущностей, которыми реально управляют GitHub/GitLab и сам runtime платформы.

## Домены первой итерации

### 1. Access and accounts (доступ, организации, группы и внешние аккаунты)
Что входит:
- пользователи платформы;
- организации;
- глобальные и организационные группы;
- права доступа;
- политики членства и наследования;
- проектные и репозиторные разрешения;
- аккаунты GitHub/GitLab;
- аккаунты Codex/OpenAI и других поставщиков моделей и runtime-контуров;
- системные настройки.

### 2. Projects and repositories (проекты, репозитории и release policy)
Что входит:
- проекты;
- репозитории внутри проекта;
- конфигурация проекта и репозитория;
- `services.yaml` policy;
- onboarding новых репозиториев;
- привязка источников проектной документации и базовых правил проекта;
- проверенный состав проектной документации для workspace по `services.yaml`;
- branch rules;
- release policies;
- релизные линии и привязки к стратегиям выкладки.

### 3. Provider-native work items (рабочие сущности провайдера)
Что входит:
- `Issue`;
- `PR/MR`;
- комментарии и mentions;
- связи;
- type / labels / milestones / поля проекта / метаданные провайдера;
- platform watermarks и открытые инструкции в body/comment слоях.

Ключевое решение:
- инициатива = `Issue` типа `initiative`;
- follow-up работа = такие же `Issue` с другими типами;
- платформа не плодит отдельную собственную рабочую сущность для инициативы.

### 4. Package platform (пакетная платформа: плагины и пакеты руководящей документации)
Что входит:
- `plugin package`;
- `guidance package`;
- каталог пакетов;
- каталог установленных пакетов;
- каталог доступных пакетов, получаемый через клиентские подключения к магазинам пакетов;
- подключение к пакету магазина пакетов как к обычному устанавливаемому пакету;
- пакет сайта и пользовательской документации платформы: API, разработка пакетов, добавление пакетов в магазин и каталог;
- репозитории-источники пакетов;
- статус верификации;
- состояние установки и импорта пакета;
- ценовые данные и метаданные каталога;
- схемы секретов и описания возможностей пакета.

Ключевое решение:
- плагины и руководящие пакеты документации не проектируются как две разные несвязанные системы;
- они сходятся в общем пакетном контракте с разными путями исполнения и импорта.
- магазин пакетов не является жёстко встроенной частью ядра: авторский магазин поставляется из приватного репозитория `github.com/codex-k8s/kodex-package-store` как пакет, а каждая установка платформы сама выбирает источники доступных пакетов. Пакетная платформа в этом контуре является клиентом магазина и владельцем локального состояния установки. Сайт и пользовательская документация платформы поставляются из приватного репозитория `github.com/codex-k8s/kodex-package-platform-site`.
- source submodule пакетов объявляются в `.gitmodules` и checkout-ятся в `packages/**`; метаданные установленных пакетов хранятся в БД и могут предзаполняться из JSON-манифеста пакета; платные пакеты проходят через прокси платформы и проверку прав.

### 5. Agent orchestration (агент-менеджер и оркестрация работы)
Что входит:
- agent-manager как центральный управляющий агент;
- разбор пользовательских запросов;
- запуск ролевых агентов;
- управление flow;
- правила расписания;
- привязки триггеров;
- продолжение сессий;
- acceptance machine;
- правила создания follow-up задач и артефактов;
- канонические flow, профили ролей и шаблоны промптов в БД;
- установочные фикстуры flow, ролей и шаблонов промптов в репозитории платформы.

### 6. Runtime and fleet (runtime-платформа, контур серверов и кластеров, слоты)
Что входит:
- реестр серверов и Kubernetes-кластеров;
- политика размещения;
- `code-only` и `full-env` execution;
- namespace-per-task slot;
- prewarmed slots;
- platform jobs для mirror/build/deploy;
- регламентные cleanup и health-check jobs;
- очистка и переинициализация слота;
- задел на nested cluster;
- подготовка окружения, миграции, фикстуры, runtime reuse.

### 7. Interaction hub (контур пользовательских взаимодействий и внешних каналов)
Что входит:
- взаимодействие через UI фронта;
- голосовой интерфейс;
- внешние каналы уведомлений и запросов;
- настраиваемые уведомления по run/job/error/action событиям;
- callback/resolution contract;
- подключаемые внешние интеграции.

Ключевое решение:
- список каналов не фиксируется заранее;
- проектируется общий расширяемый контракт;
- механизм реализации (плагины, адаптеры, OpenAPI-контракт, гибрид) выбирается отдельным design-срезом.

### 8. Console and operations UX (консоль и операционные интерфейсы)
Что входит:
- центральный чат с agent-manager;
- управление проектами, репозиториями, доступами;
- рабочие представления по задачам;
- операционные статусы и диагностика;
- UX для запуска flow и наблюдения за выполнением;
- экраны каталогов пакетов, контура серверов и кластеров, биллинга и настроек автоматизации.

### 9. Billing and cost accounting (биллинг и учёт затрат)
Что входит:
- записи затрат;
- распределение по организациям, проектам и другим контурам;
- usage внешних провайдеров и runtime;
- основа для счёта;
- задел под платёжных провайдеров;
- экономика каталога пакетов.

### 10. Risk and release governance (управление рисками и релизами)
Что входит:
- классификация риска;
- матрица контрольных точек ревью;
- пакет данных для релизного решения;
- правила Human gate;
- правила, когда owner утверждает документы, high-risk переходы и релизы, а не обязательно код построчно;
- правила безопасной автоматизации без участия человека;
- релизные ветки, релизные линии и политики выкладки.

Это не опциональный домен. Он должен закладываться с самого начала, даже если полная реализация будет позже.

### 11. Knowledge lifecycle (документация и жизненный цикл знаний)
Что входит:
- шаблоны документов;
- project rules для агентов;
- пакеты руководящей документации;
- источники и структура проектной документации в репозиториях проекта;
- загрузка проектной документации в workspace вместе с кодом и руководящими пакетами;
- будущий переход к knowledge storage через векторные БД и MCP.

Ключевое решение:
- руководящая документация живёт как пакет и описывает общие правила работы агентов;
- шаблоны документации живут отдельно от руководящих пакетов, публичный источник шаблонов — `github.com/codex-k8s/kodex-doc-templates-ru`, а в `kodex` он подключён как source submodule `docs/templates`;
- проектная документация живёт в репозиториях проекта и описывается через `services.yaml`;
- flow, профили ролей и шаблоны промптов живут в БД, а репозиторий платформы хранит только установочные фикстуры.

## Cross-cutting требования
- Приоритет нативной модели провайдера.
- Минимум внутренней правды поверх состояния провайдера и runtime.
- Апрувы на основе риска.
- Дисциплина компактных PR.
- Русскоязычная документация без лишнего смешивания с английским.

## Что будет спроектировано позже
- Точная сервисная карта и количество внутренних сервисов.
- Точный контракт внешних interaction channels.
- Точная модель risk classes и release gates.
- Точный frontend information architecture.
