# Архитектура приложения

Документ описывает модульную архитектуру backend-приложения, связи между модулями и контрактные границы.

## 1. Диаграмма модулей и взаимосвязей

```mermaid
flowchart LR
    UI["Клиент / Frontend"] --> API["FastAPI (app/main.py)"]

    API --> CHAT["chat модуль"]
    API --> RAG["rag модуль"]
    API --> AGENT_INTERNAL["internal tools API"]

    CHAT -->|AgentRunner| AGENT["agent модуль"]
    AGENT -->|RagRetriever| RAG
    AGENT --> DB[(PostgreSQL + pgvector)]
    CHAT --> DB
    RAG --> DB

    AGENT --> GIGA["GigaChat API"]
    RAG --> GIGA

    AGENT_INTERNAL --> AGENT

    APP["ModularApplication\n(app/modules/application.py)"] --> CHAT
    APP --> AGENT
    APP --> RAG
```

### Внутренние слои `agent`

```mermaid
flowchart TB
    ROUTER["Router\n(intent + context)"] --> ORCH["Orchestrator\n(task spec + plan + execution + quality)"]
    ORCH --> GRAPHS["Action Graphs\nLangGraph"]

    ORCH --> METRICS["Quality Metrics\n(faithfulness/coverage)"]
    METRICS --> DB[(agent_quality_metrics)]
```

## 2. Описание модулей

### Модуль `app/modules/chat`

- Цель: принять пользовательский запрос, управлять задачей обработки, отдать результат и прогресс.
- Кратко о реализации:
  - `ChatModule` публикует HTTP API (`/api/chat/*`, `/api/tasks/*`, `/api/events`).
  - `ChatOrchestrator` запускает обработку асинхронной задачи, публикует SSE-события, обрабатывает retry и ошибки.
  - `TaskStore`, `DialogSessionStore`, `IdempotencyStore` держат состояние задач/диалогов.
- С кем взаимодействует:
  - с `agent` через контракт `AgentRunner`.
  - с `rag` для проверки `rag_session_id`.
  - с `shared/event_bus` для стриминга прогресса.
  - с БД через `ChatRepository` (`dialog_sessions`, `chat_messages`).
- Контракты:
  - потребляет `AgentRunner.run(...)` из `app/modules/contracts.py`.

### Модуль `app/modules/agent`

- Цель: интеллектуальная обработка запроса, маршрутизация, оркестрация сценария, генерация ответа/changeset.
- Кратко о реализации:
  - `GraphAgentRuntime` выполняет pipeline: route -> task spec -> orchestrator -> post-processing.
  - Router (`engine/router/*`) выбирает `domain/process` и хранит routing-context.
  - Orchestrator (`engine/orchestrator/*`) строит и валидирует plan, исполняет шаги, запускает графовые/функциональные actions.
  - Graphs (`engine/graphs/*`) выполняют целевые действия (QA, edits, docs).
  - Рассчитывает quality-метрики (`faithfulness`, `coverage`) и сохраняет их в БД.
  - Поддерживает внутренний инструмент получения страниц Confluence (`/internal/tools/confluence/fetch`).
- С кем взаимодействует:
  - с `rag` через контракт `RagRetriever`.
  - с `shared/checkpointer` (LangGraph checkpoints в PostgreSQL).
  - с GigaChat (LLM-запросы, промпты).
  - с БД через `AgentRepository` (`router_context`, `agent_quality_metrics`).
- Контракты:
  - реализует `AgentRunner` (используется `chat`).
  - потребляет `RagRetriever` (реализуется `rag`).

### Модуль `app/modules/rag`

- Цель: индексация проектных файлов и retrieval релевантного контекста.
- Кратко о реализации:
  - API для snapshot/changes индексации и retrieval.
  - Индексация хранит чанки, эмбеддинги и состояние job.
  - Retrieval ищет релевантные куски в `rag_chunks` (pgvector).
- С кем взаимодействует:
  - с `agent` (выдача контекста через `RagRetriever`).
  - с БД (`rag_sessions`, `rag_chunks`, `rag_index_jobs`).
  - с GigaChat Embeddings.
- Контракты:
  - реализует `RagRetriever` и `RagIndexer` из `app/modules/contracts.py`.

### Модуль `app/modules/shared`

- Цель: общие инфраструктурные компоненты, переиспользуемые всеми модулями.
- Кратко о реализации:
  - `db.py`: engine/session factory.
  - `event_bus.py`: pub/sub для SSE.
  - `retry_executor.py`: общий retry.
  - `checkpointer.py`: PostgresSaver для LangGraph.
  - `bootstrap.py`: инициализация схем БД на старте.
- С кем взаимодействует:
  - со всеми бизнес-модулями (`chat`, `agent`, `rag`).
- Контракты:
  - внутренние инфраструктурные API без отдельного публичного контракта уровня `contracts.py`.

### Модуль `app/modules/contracts.py`

- Цель: зафиксировать межмодульные интерфейсы и отделить реализацию от потребителей.
- Кратко о реализации:
  - `AgentRunner`, `RagRetriever`, `RagIndexer` определены как `Protocol`.
- С кем взаимодействует:
  - используется `chat` (как потребитель `AgentRunner`), `agent` (как потребитель `RagRetriever`), `rag` (как реализация `RagRetriever`/`RagIndexer`).
- Контракты:
  - это и есть контрактный слой.

### Модуль композиции `app/modules/application.py`

- Цель: централизованный wiring зависимостей.
- Кратко о реализации:
  - `ModularApplication` создаёт `EventBus`, `RetryExecutor`, репозитории и модули.
  - На `startup()` выполняет bootstrap БД.
- С кем взаимодействует:
  - со всеми модулями, но не содержит бизнес-логики.
- Контракты:
  - использует `contracts.py` для сборки зависимостей без жёсткого сцепления по реализациям.

## 3. Ключевые контрактные границы

- `chat -> agent`: только через `AgentRunner`.
- `agent -> rag`: только через `RagRetriever`.
- `rag`: не зависит от `agent` internals.
- `application.py`: единственная точка связывания реализаций.

## 4. Схема данных (кратко)

- `chat`: `dialog_sessions`, `chat_messages`.
- `rag`: `rag_sessions`, `rag_chunks`, `rag_index_jobs`.
- `agent`:
  - `router_context` — контекст маршрутизации по диалогу.
  - `agent_quality_metrics` — пер-сценарные quality-метрики для отчетности:
    - `faithfulness_score`, `coverage_score`, `quality_status`, `metrics_json`, `created_at`.
  - `story_records` — карточка Story (статус, владелец, метаданные).
  - `story_artifacts` — артефакты по Story (analytics/doc_increment/test_model и версии).
  - `story_links` — внешние связи Story (тикеты, документы, URL).

## 5. Поток обработки запроса

1. Пользователь отправляет сообщение в `chat`.
2. `chat` создаёт task и вызывает `AgentRunner.run(...)`.
3. `agent/router` выбирает маршрут (domain/process).
4. `agent/orchestrator` строит `TaskSpec` и `ExecutionPlan`.
5. Выполняются шаги плана (function/actions/graph steps).
6. Формируется `answer` или `changeset`.
7. Считаются `faithfulness/coverage`, сохраняются в `agent_quality_metrics`.
8. `chat` возвращает результат и стримит прогресс через SSE.