# Блок 1. Архитектура: компоненты и связи

> Обзорный уровень. Полная таблица компонентов с деталями и историей решений — в
> [инженерном справочнике](../architecture/README.md) («Компоненты») и
> [internals](../architecture/internals.md); здесь — цельная картина, как части складываются
> в конвейер.

## Поток одной задачи

```
            Plane (трекер)            Gitea (git/CI)
                 │ вебхук                  │ вебхук
                 ▼                         ▼
        ┌────────────────────────────────────────┐
        │   FastAPI-приём (HMAC-подпись, дедуп)  │
        └───────────────────┬────────────────────┘
                            ▼
   вебхук → очередь (jobs) → агент (Claude CLI в worktree) → гейт (QG) → переход стадии
                            ▲                                              │
                            └────────── следующая стадия / откат ◄─────────┘
```

Каждое продвижение задачи — один и тот же цикл: событие принято → в очередь поставлен job →
worker запустил агента стадии → результат проверен гейтом качества → state machine перевела
задачу на следующую стадию (или откатила назад).

## Компоненты

| Компонент | Роль |
|-----------|------|
| **Webhook-приёмники** (`src/webhooks/`) | Принимают события Plane (статусы задач) и Gitea (push, PR, CI). Проверяют HMAC-подпись, дедуплицируют повторные доставки. |
| **Очередь задач** (`jobs` + worker) | Собственная очередь на SQLite: атомарный захват job'а, ретраи с backoff, зависимости между job'ами, ограничение параллелизма. |
| **State machine** (`src/stages.py`) | Карта стадий `STAGE_TRANSITIONS`: для каждой стадии — следующая, агент и гейт выхода. Единственный источник истины о конвейере. |
| **Stage engine** (`src/stage_engine.py`) | Исполняет переходы: диспетчеризация гейтов, откаты, под-гейты деплойного ребра, синхронизация статусов с Plane. |
| **Agent launcher** (`src/agents/launcher.py`) | Запускает Claude CLI агента в изолированном git worktree ветки задачи, следит за процессом (watchdog), авто-продвигает стадию по завершении. |
| **Реестр гейтов** (`src/qg/checks.py`) | `QG_CHECKS` — машинные проверки выхода со стадий; вердикты читаются только из YAML-frontmatter артефактов. |
| **Plane-sync** (`src/plane_sync.py`) | Индикация статусов в Plane (слой «показать человеку», никогда не управление конвейером). |
| **Notifications** (`src/notifications.py`) | Живая Telegram-карточка задачи и алерты. |

## Фоновые демоны (самовосстановление)

Поднимаются в lifespan FastAPI-приложения (`src/main.py`) и работают рядом с конвейером:

- **reconciler** — находит расхождения «БД говорит одно, реальность другое» (зависшие стадии,
  потерянные ветки) и возвращает задачи в консистентное состояние;
- **job-reaper** — возвращает в очередь job'ы, чей исполнитель умер (упавший процесс, рестарт);
- **disk-watchdog** — следит за местом на диске, чистит устаревшие worktree;
- **build-cache-pruner** — прибирает докер-кэш сборок.

Отдельно от приложения живёт **sidecar-watchdog** — независимый контейнер-наблюдатель: следит
за самим оркестратором снаружи (health, метрики) и шлёт алерты в собственный Telegram-канал.
Наблюдатель сознательно отделён от наблюдаемого: падение оркестратора не валит сторожа.

## Изоляция работы агентов

Каждая задача живёт в собственной git-ветке (`feature/<ID>-slug`) и собственном **worktree** —
изолированной рабочей копии репозитория. Агенты разных задач не видят незакоммиченную работу
друг друга; слияние в `main` происходит только через PR в Gitea после всех гейтов.

---

*Подробнее: [компоненты и API](../architecture/README.md) · [внутренности и схема БД](../architecture/internals.md) ·
следующий блок — [конвейер и стадии](tech-pipeline.md).*