docs: recreate documentation structure with updated specs

docs/architecture/overview.md

@@ -1,25 +1,53 @@
-# Architecture Overview
+# Обзор Архитектуры Контакт-Центра (MVP)
 
-## Services
-- api-gateway
-- auth-service
-- audit-service
-- customer-service
-- interaction-service
-- routing-service
-- voice-adapter-service
-- telegram-adapter-service
-- kb-service
-- reporting-service
-- supervisor-service
+Контакт-центр спроектирован на базе микросервисной архитектуры с использованием событийно-ориентированного подхода (Event-Driven Architecture). Описываемая платформа поддерживает омниканальные коммуникации (Голос, Telegram, Email, Webchat, WhatsApp) с глубокой интеграцией AI-операторов (Voice AI V1, Telegram AI) и полноценной системой маршрутизации.
 
-## Data and event strategy
-- All services use SQL storage via `DATABASE_URL`
-- Default local mode: SQLite (`.data/mvp_cc.db`)
-- Target mode: PostgreSQL (supported in `deployment/docker-compose.yml`)
-- Contract-first API and JSON event schema artifacts
-- Event contracts are fixed and ready for message bus integration (RabbitMQ/Kafka) in next phase
+## 1. Основные компоненты (Микросервисы)
 
-## Deployment
-- Local: Docker Compose
-- On-prem: Kubernetes manifests and Helm chart
+Архитектура состоит из множества независимых сервисов, написанных на Python (FastAPI):
+
+### Базовые и инфраструктурные сервисы
+- **`api-gateway`** — Единая точка входа для клиентских интерфейсов (UI оператора/супервизора/админа).
+- **`auth-service`** — Сервис аутентификации и RBAC. Поддерживает OIDC (Keycloak) и авторизацию по `APP_TOKEN_SECRET`.
+- **`audit-service`** — Служба записи логов аудита системных действий (подключена к шине событий).
+- **`event-bus-service`** — Асинхронная шина событий. Реализует паттерн Transactional Outbox/Inbox поверх брокера **RabbitMQ** для надежной доставки сообщений между сервисами.
+
+### Клиентоцентричные сервисы и роутинг
+- **`customer-service`** — Хранит профили клиентов. Управляет связыванием номеров телефонов и Telegram/Webchat-аккаунтов в единый профиль (`customer_external_identities`).
+- **`interaction-service`** — Канонический источник истины об "обращениях" (Interactions). Хранит таймлайн общения клиента и статусы тикетов.
+- **`routing-service`** — Умная маршрутизация: оценка занятости сотрудников, скилл-бейзд роутинг, распределение по очередям.
+
+### Телефония и Медиа каналы (Adapters)
+- **`asterisk-bridge-service`** — Главный мост с Asterisk телефонией (перехват AMI-событий с префиксом `MVPCC`). Отслеживает звонки, трансферы и командует Asterisk'ом.
+- **`ivr-service`** — Сервис голосового меню. Настраивает IVR потоки (flows) через интерфейс администратора и обрабатывает DTMF клики.
+- **`recording-service`** — Сервис управления записями звонков. Позволяет скачивать (SFTP) и локально управлять аудиофайлами звонков.
+- **`voice-adapter-service`** — Сохраняет события жизненного цикла звонков в БД.
+- **`telegram-adapter-service`** / **`email_adapter_service`** / **`webchat_adapter_service`** / **`whatsapp_adapter_service`** — Адаптеры интеграции с внешними цифровыми каналами (мессенджерами и веб-чатами).
+
+### Интеллект и База Знаний (AI & KB)
+- **`kb-service`** — Локальная База Знаний. Содержит категории, статьи и обеспечивает быстрый поиск.
+- **`ai_orchestrator_service`** — Детерминированный мозг ИИ. Принимает решения о генерации ответа или передаче диалога (Handoff) оператору на основе контекста и бизнес-правил.
+- **`ai_voice_runtime_service`** — Реал-тайм прослойка аудио-моста (Speech-to-Text / Text-to-Speech) для голосового робота. Обрабатывает перебивания (barge-in) в реальном времени.
+
+### Аналитика, Отчетность и Надзор
+- **`reporting-service`** — Агрегация KPI (Service Level, ASA, AHT, Abandon Rate, FCR) в разрезе каналов и агентов.
+- **`supervisor-service`** — "Живой" мониторинг контакт-центра (статусы агентов, метрики, прослушка записей).
+
+## 2. Пользовательские Интерфейсы (UI Shells)
+
+Проект предоставляет несколько разделенных рабочих сред:
+- `/operator` — Единое окно оператора (Обработка звонков: «Взять в работу», «Трансфер», «Сброс», переписка Telegram/Webchat). ИИ-сводки по звонкам.
+- `/supervisor` — Окно супервизора (Мониторинг очередей, статусов агентов, поиск и прослушивание записей звонков из `recording-service`).
+- `/admin` — Администрирование (Назначение ролей, управление очередями, конфигурация IVR деревьев, превью маршрутизации).
+- `/analyst` — Выгрузки и детальная панель исторических KPI и отчетов.
+
+## 3. Стратегия Данных и Развертывание
+
+1. **Хранение данных:** Каждый микросервис спроектирован так, чтобы иметь изолированную логическую базу. 
+   - По умолчанию используется локальный **SQLite**.
+   - Для K8s Scale/Продакшена используется **PostgreSQL** DB Pooling (настраивается через переменные `DB_POOL_SIZE`, `DB_MAX_OVERFLOW`).
+   - Исходным механизмом миграций является `Alembic` (скрипт `scripts/migrate_core_db.py`).
+2. **Инфраструктура / Развертывание:** 
+   - Разработка ведется через локальные Docker Compose конфигурации (`docker-compose.yml`, `docker-compose.server.yml`). Готов набор PS/Bash скриптов в директории `scripts/` (например, `scripts/prepare_demo.ps1`).
+   - Для серверов и Enterprise масштабов написаны Kubernetes Helm Chart (`deployment/helm`) и K8s манифесты.
+   - Шина **RabbitMQ** используется как канонический брокер сообщений для `event_outbox`/`event_inbox` логики обмена.