---
doc_id: ARC-CK8S-C4C-0001
type: c4-context
title: kodex — C4 Context
status: active
owner_role: SA
created_at: 2026-04-26
updated_at: 2026-04-26
related_issues: [599, 600, 601, 602]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-architecture-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# C4 Context: kodex

## Кратко

`kodex` — платформа управления агентной разработкой с обязательной опорой на Kubernetes. Она не заменяет GitHub/GitLab, а управляет задачами, агентами, средами исполнения, доступами, пакетами, релизами, уведомлениями и операторскими решениями поверх нативных артефактов провайдера.

## Система в контуре

Платформа отвечает за:
- управление организациями, пользователями, группами и доступом;
- проекты, репозитории, проектную документацию и релизные политики;
- зеркальные проекции `Issue`, `PR/MR`, комментариев и связей;
- agent-manager, процессы, роли, шаблоны промптов, агентные запуски и приёмку;
- слоты, платформенные задания, серверы, Kubernetes-кластеры и среды исполнения;
- пакетную платформу, плагины, пакеты руководящей документации и магазины пакетов;
- взаимодействие с человеком через пользовательский интерфейс, голос, уведомления и внешние каналы;
- биллинг, учёт затрат, риск, релизы и операционные витрины.

Платформа не становится владельцем:
- исходного состояния `Issue`, `PR/MR`, review, веток и тегов у провайдера;
- полного контейнерного лога и состояния Kubernetes-нагрузки;
- реестра образов как отдельной внутренней модели;
- содержимого проектной документации и кода вне разрешённых изменений нативных артефактов провайдера.

## Участники

| Участник | Как взаимодействует с платформой |
|---|---|
| Пользователь платформы | Работает через web-console, голос, командный центр, задачи и комментарии провайдера. |
| Владелец | Утверждает документы, рискованные переходы, Human gate и релизные решения по политике. |
| Оператор платформы | Следит за очередями, заданиями, слотами, кластерами, ошибками и уведомлениями. |
| Ролевой агент | Выполняет работу в слоте, создаёт нативные артефакты провайдера и использует платформенный MCP для разрешённых операций. |
| Agent-manager | Быстро управляет запросами, выбирает процесс и роль, запускает ролевых агентов и принимает промежуточные решения. |
| Разработчик пакета | Поставляет пакет плагина, руководящий пакет или пакет магазина по контракту пакетной платформы. |
| Администратор организации | Управляет пользователями, группами, внешними аккаунтами, проектами и инфраструктурными ограничениями. |

## Внешние системы

| Система | Роль |
|---|---|
| GitHub/GitLab | Нативные рабочие артефакты провайдера: `Issue`, `PR/MR`, комментарии, review, ветки, теги и связи. |
| Kubernetes | Среда исполнения для платформы, слотов, нагрузок плагинов и проектных окружений. |
| Реестр контейнерных образов | Источник истины по образам, тегам и манифестам. |
| Vault | Каноническое хранилище секретов платформы и её зависимостей. |
| Keycloak или другой IdP | Базовый SSO/OIDC-контур входа пользователей платформы. |
| Поставщики моделей | Модели для agent-manager, ролевых агентов и специализированных проверок. |
| Объектное хранилище | Временные голосовые и медиа-вложения, если они нужны для взаимодействия. |
| Внешние каналы | Telegram, email, webhook и будущие каналы через пакеты и общий контракт взаимодействия. |
| Платёжные провайдеры | Будущий контур оплат и выставления счетов. |

## Диаграмма

```mermaid
C4Context
title kodex - системный контекст

Person(user, "Пользователь платформы", "Создаёт задачи, общается с agent-manager, принимает решения")
Person(owner, "Владелец", "Утверждает документы, риски, Human gate и релизы")
Person(operator, "Оператор", "Наблюдает за заданиями, слотами, очередями и сбоями")
Person(packageDev, "Разработчик пакета", "Поставляет плагины и руководящие пакеты")

System(kodex, "kodex", "Платформа управления агентной разработкой")

System_Ext(provider, "GitHub/GitLab", "Issue, PR/MR, review, ветки, теги")
System_Ext(k8s, "Kubernetes", "Среды исполнения, слоты, нагрузки плагинов")
System_Ext(registry, "Реестр контейнерных образов", "Образы, теги, манифесты")
System_Ext(vault, "Vault", "Секреты платформы и зависимостей")
System_Ext(idp, "SSO/OIDC IdP", "Вход пользователей")
System_Ext(models, "Поставщики моделей", "LLM для агентов")
System_Ext(channels, "Внешние каналы", "Уведомления, согласования, обратная связь")
System_Ext(payments, "Платёжные провайдеры", "Будущий биллинг")

Rel(user, kodex, "Управляет работой", "HTTPS, голос, упоминания у провайдера")
Rel(owner, kodex, "Принимает решения", "HTTPS, уведомления")
Rel(operator, kodex, "Наблюдает и управляет", "HTTPS")
Rel(packageDev, kodex, "Публикует пакеты", "Нативные PR/MR провайдера")
Rel(kodex, provider, "Читает и меняет нативные артефакты провайдера", "Webhook, API, CLI")
Rel(kodex, k8s, "Создаёт слоты, задания и нагрузки плагинов", "Kubernetes API")
Rel(kodex, registry, "Публикует и использует образы", "OCI")
Rel(kodex, vault, "Читает секреты платформы", "Vault API")
Rel(kodex, idp, "Проверяет вход", "OIDC")
Rel(kodex, models, "Запускает агентов", "API провайдера")
Rel(kodex, channels, "Доставляет уведомления и запросы", "Контракты плагинов")
Rel(kodex, payments, "Учитывает и принимает оплаты", "API платежей")
```

## Границы ответственности

- Провайдер остаётся источником истины для рабочих артефактов.
- Kubernetes остаётся источником истины для объектов среды исполнения и полных логов.
- Платформа хранит каноническое состояние оркестрации, доступа, жизненного цикла сред исполнения, приёмки, политик, биллинга, уведомлений и операторских проекций.
- Пользовательский интерфейс питается от платформенных проекций и не должен читать провайдера напрямую на каждый экран.
- Агент в слоте может работать через `gh` или API провайдера, но обязан передавать платформе идентификаторы созданных или изменённых артефактов как сигнал для синхронизации.

## Апрув

- request_id: `owner-2026-04-26-platform-architecture-frame`
- Решение: approved
- Комментарий: C4-контекст входит в сквозной архитектурный каркас платформы.
