156 lines
8.3 KiB
Markdown
156 lines
8.3 KiB
Markdown
# Архитектура приложения
|
||
|
||
Документ описывает модульную архитектуру 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.
|