# Витрина системы — Orchestrator

**Что это за система.** Orchestrator — автономная фабрика разработки: конвейер из шести
ИИ-агентов (аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер), который
проводит задачу от бизнес-постановки до выкладки на прод. Человек ставит задачу и принимает
результат; всё между — автономно, под защитой машинных гейтов качества. Платформа ведёт
несколько проектов из одного инстанса, дорабатывает сама себя (self-hosting) и тиражируется
на новые хосты.

**Зачем эта витрина.** Это единая точка входа в документацию системы: связное описание на двух
уровнях — бизнес (для нетехнического читателя) и технический (7 блоков), с маршрутами чтения
для трёх аудиторий и слайдо-готовой основой для презентации. Витрина — обзор; за деталями она
ведёт ссылками в инженерные golden sources, не подменяя их.

---

## Состав витрины

| Файл | О чём |
|------|-------|
| [business.md](business.md) | Бизнес-уровень: проблема, решение, что умеет, ценность, сценарии |
| [tech-architecture.md](tech-architecture.md) | Блок 1: компоненты и связи, схема потока |
| [tech-pipeline.md](tech-pipeline.md) | Блок 2: конвейер, стадии, гейты, откаты, человеческие гейты |
| [tech-agents.md](tech-agents.md) | Блок 3: 6 ролей агентов, артефакты, модель/эффорт |
| [tech-data-model.md](tech-data-model.md) | Блок 4: каноническая модель объектов, словарь терминов |
| [tech-integrations.md](tech-integrations.md) | Блок 5: Plane, Gitea, LLM, Telegram |
| [tech-quality-security.md](tech-quality-security.md) | Блок 6: гейты качества, безопасность, секреты |
| [tech-observability.md](tech-observability.md) | Блок 7: наблюдаемость, аналитика, журнал уроков |
| [presentation.md](presentation.md) | Слайдо-источник презентации + сборка `.pptx` |

---

## Маршруты чтения

### Я заказчик
1. [business.md](business.md) — проблема, решение, ценность.
2. [business.md → Сценарии использования](business.md#сценарии-использования) — как это выглядит в работе.
3. [presentation.md](presentation.md) — слайдовая версия рассказа (собирается в PowerPoint).
4. Развернуть у себя: [LITE_SETUP](../deployment/LITE_SETUP.md) (своя инфраструктура) или
   [BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md) (весь стек одним комплектом).

### Я менеджер проекта
1. [business.md](business.md) — что платформа делает и где в процессе человек.
2. [tech-pipeline.md](tech-pipeline.md) — конвейер, статусная модель Plane, человеческие гейты
   (одобрение постановки, подтверждение прод-деплоя).
3. [tech-observability.md](tech-observability.md) — как следить за ходом: живая Telegram-карточка,
   статусы, стоимость.

### Я разработчик
1. Тех-блоки 1→7: [архитектура](tech-architecture.md) → [конвейер](tech-pipeline.md) →
   [агенты](tech-agents.md) → [модель объектов](tech-data-model.md) →
   [интеграции](tech-integrations.md) → [качество/безопасность](tech-quality-security.md) →
   [наблюдаемость](tech-observability.md).
2. [Инженерный справочник архитектуры](../architecture/README.md) и
   [internals](../architecture/internals.md) — детали реализации.
3. [Стандарты](../_standards/PIPELINE_DOCS.md) (структура доков конвейера),
   [HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md) (машинный контракт стадий),
   [TRACEABILITY](../_standards/TRACEABILITY.md) (маркеры решений).
4. [Реестр сквозных ADR](../architecture/adr/) — история архитектурных решений.
5. [CLAUDE.md](../../CLAUDE.md) — паспорт проекта и правила для агентов.

---

## Норматив сопровождения

> **Изменил функциональность платформы → обнови витрину `docs/overview/` в том же PR.**

Какой файл правится при каком классе изменений:

| Класс изменения | Файл витрины |
|-----------------|--------------|
| Новый компонент / демон / поток данных | [tech-architecture.md](tech-architecture.md) |
| Стадии, гейты, под-гейты, маршруты задач | [tech-pipeline.md](tech-pipeline.md) |
| Роли агентов, промпты, модель/эффорт | [tech-agents.md](tech-agents.md) |
| Таблицы БД, объекты, термины | [tech-data-model.md](tech-data-model.md) |
| Plane / Gitea / LLM / Telegram | [tech-integrations.md](tech-integrations.md) |
| Гейты качества, секреты, self-hosting-страховки | [tech-quality-security.md](tech-quality-security.md) |
| Эндпоинты наблюдаемости, метрики, уроки | [tech-observability.md](tech-observability.md) |
| Новая способность уровня продукта | [business.md](business.md) + при необходимости [presentation.md](presentation.md) |

Каркас и машинно-проверяемые факты витрины (перечень стадий, имена гейтов, полнота агентов,
валидность ссылок) защищены структурными тестами `tests/test_system_docs.py` — дрейф рвёт CI.
Прозу проверяет reviewer: необновлённая витрина при изменении описанной в ней функциональности —
finding ≥ P1 (расширение оси обзорных доков).

---

*Витрина — обзорный слой документации. Текущее состояние и реестр доработок — [CLAUDE.md](../../CLAUDE.md);
концепция развития — [Product Vision](../PRODUCT_VISION.md).*