01. Архитектура¶

1. Принципы¶

Enterprise-first, микросервисы с первого дня. Монолит как промежуточный этап не рассматриваем (обоснование отклонения — ниже).
Разделение Control Plane / Data Plane. Управление и рантайм масштабируются и защищаются независимо.
Bounded contexts. Границы сервисов проводятся по смысловым областям домена.
Асинхронность по умолчанию. Взаимодействие через шину событий; синхронные вызовы — через контрактные API.
Сага вместо распределённых транзакций. Согласованность между сервисами — через компенсации.
IaC + Kubernetes + GitOps. Вся инфраструктура декларативна и воспроизводима.
Observability и HA — базовые требования.

Почему не модульный монолит (отклонённая альтернатива)¶

Монолит дешевле и быстрее на старте, но требование бизнеса — «сразу под enterprise и масштаб». Переход монолит → микросервисы позже несёт риск и объём работы по декомпозиции, которых мы избегаем, начиная сразу с микросервисов. Компромисс (более сложный и дорогой старт) принят осознанно.

2. Верхнеуровневая структура (C4: контейнеры)¶

flowchart TB
    subgraph edge [Периметр]
        widget[Web-виджет / SDK]
        api[API Gateway + Auth]
    end

    subgraph cp [Control Plane - управление]
        admin[Admin / Конструктор агентов]
        tenantsvc[Tenant & Identity Service]
        billing[Billing & Quotas]
        config[Agent Config Service]
        analytics[Analytics & Metrics]
    end

    subgraph dp [Data Plane - рантайм]
        channels[Channel Service]
        orch[Agent Orchestrator]
        llmgw[LLM Gateway]
        rag[RAG / Knowledge Service]
        integ[Integration Service]
        sched[Scheduling Service]
    end

    subgraph infra [Инфраструктура]
        bus[(Event Bus - Kafka/NATS)]
        pg[(PostgreSQL per-tenant)]
        vec[(Qdrant - вектор-БД)]
        redis[(Redis)]
        obj[(S3 object storage)]
        gpu[GPU-пулы: Qwen на vLLM]
        cloudllm[Облачный Qwen API - фолбэк]
    end

    widget --> api
    api --> channels
    api --> admin
    admin --> config
    config --> orch
    billing --> orch
    channels --> orch
    orch --> llmgw
    llmgw --> gpu
    llmgw --> cloudllm
    orch --> rag
    rag --> vec
    orch --> integ
    orch --> sched
    integ --> extcrm[Внешние CRM / системы]
    orch -. события .-> bus
    bus -. события .-> analytics
    orch --> pg
    orch --> redis
    rag --> obj

3. Сервисы и их зоны ответственности (bounded contexts)¶

Control Plane¶

Tenant & Identity Service — тенанты, пользователи, роли (RBAC), API-ключи, OAuth/OIDC. Провижининг ресурсов тенанта на онбординге.
Agent Config Service — хранение, валидация и версионирование конфигов агентов; blueprints; hot-reload в рантайм.
Billing & Quotas — тарифы, учёт потребления (токены, диалоги, показы), лимиты и rate-limiting.
Admin / Конструктор агентов — UI и API для создания/настройки агентов в пару кликов.
Analytics & Metrics — бизнес-метрики (конверсия лид→показ, no-show, время ответа, стоимость показа) на основе событий из шины.

Data Plane¶

Channel Service — приём/отправка сообщений через адаптеры каналов (web, WhatsApp, Telegram, email, телефония). Нормализация в единый формат сообщения. Единый профиль контакта (identity resolution) для склейки каналов.
Agent Orchestrator — ядро: конечный автомат диалога, планирование, вызов инструментов (function calling), управление состоянием разговора, политика эскалации на человека.
LLM Gateway — маршрутизация запросов по ярусам моделей, батчинг, лимиты, фолбэк на облако (см. 05).
RAG / Knowledge Service — ингест и индексация базы знаний тенанта, семантический поиск, актуализация (TTL/переиндексация).
Integration Service — коннекторы к внешним системам (CRM и т.д.), вебхуки, маппинг полей (см. 04).
Scheduling Service — слоты, доступность менеджеров/объектов, назначение показа, напоминания, обработка неявок.

4. Поток обработки лида (runtime)¶

flowchart LR
    in[Входящее сообщение] --> ch[Channel Service]
    ch --> orch[Orchestrator]
    orch --> guard{Guardrails и антиспам}
    guard -->|мусор| drop[Отклонить / пометить]
    guard -->|ок| route[LLM Gateway: роутинг]
    route -->|простое| small[Малая модель]
    route -->|сложное| brain[Основной мозг 27-35B]
    brain --> ragq[(RAG)]
    small --> decide[Решение / действие]
    brain --> decide
    decide -->|нужен показ| sched[Scheduling]
    decide -->|данные в CRM| integ[Integration Service]
    decide -->|нужен человек| esc[Эскалация менеджеру]
    sched --> reply[Ответ в канал]
    integ --> reply
    esc --> reply

5. Взаимодействие сервисов¶

Синхронно (gRPC/REST через API Gateway): пользовательские запросы, где нужен немедленный ответ (сообщение → ответ агента).
Асинхронно (шина событий Kafka/NATS): доменные события (lead.created, showing.scheduled, handoff.completed) — для аналитики, биллинга, интеграций, уведомлений. Развязывает сервисы и повышает устойчивость.
Саги: многошаговые бизнес-операции (обработка лида → сделка в CRM → показ → подтверждение) с компенсациями при сбое шага.

6. Отказоустойчивость¶

HA: минимум 2 реплики каждого сервиса, кластер PostgreSQL с репликами, реплицированные топики шины.
Circuit breaker + retry на всех внешних вызовах (CRM, каналы, облачный LLM).
Graceful degradation: недоступен RAG → агент отвечает без него; недоступна аналитика → диалоги продолжаются.
Фолбэк инференса: локальный GPU недоступен/перегружен → LLM Gateway переключает на облачный Qwen API.

7. Технологический стек¶

Языки/рантайм: Python (агент/ML-часть, оркестрация, RAG), Go/TypeScript (высоконагруженные сервисы каналов/шлюзов) — по контексту.
Оркестрация LLM-логики: LangGraph-подобный подход или собственный конечный автомат.
Serving LLM: vLLM / SGLang.
Данные: PostgreSQL (per-tenant), Qdrant (вектор-БД), Redis (кэш/состояние), S3-совместимое объектное хранилище.
Шина: Kafka или NATS JetStream.
Инфраструктура: Kubernetes, Terraform (IaC), GitOps (ArgoCD/Flux).
Observability: OpenTelemetry + Prometheus + Grafana + централизованные логи.
API Gateway / Auth: OAuth2/OIDC, per-tenant API keys, rate-limiting.