Аудит архитектуры: связи подсистем, проблемы, рекомендации

[shikhalev]

Контекст

Анализ текущих связей между подсистемами AI Secretary System. Цель — зафиксировать как подсистемы взаимодействуют, где проблемы, и как должно быть правильно.

---

1. Карта подсистем

                    ┌─────────────────────────────────────────────┐
                    │         orchestrator.py (~4100 строк)        │
                    │  God Object: startup, DI, ~100 legacy API,  │
                    │  widget endpoints, background tasks          │
                    ├──────────────┬───────────────┬──────────────┤
                    │              │               │              │
              ┌─────┴─────┐  ┌────┴────┐   ┌──────┴──────┐  ┌───┴───┐
              │ 26 Routers │  │ Service │   │ DB Layer    │  │ Caches│
              │ app/       │  │ Layer   │   │ db/         │  │       │
              │ routers/   │  │ (split) │   │             │  │       │
              └─────┬──────┘  └────┬────┘   └──────┬──────┘  └───┬───┘
                    │              │               │              │
        ┌───────────┼──────────────┼───────────────┤              │
        │           │              │               │              │
   ┌────┴───┐ ┌────┴───┐   ┌─────┴──────┐  ┌────┴─────┐  ┌────┴────┐
   │TG Bot  │ │WA Bot  │   │Root svc:   │  │db/integr.│  │In-memory│
   │subproc │ │subproc │   │cloud_llm,  │  │30+ mgr   │  │5 кешей  │
   │(HTTP→  │ │(HTTP→  │   │voice,stt   │  │singletons│  │+ Redis  │
   │ orch)  │ │ orch)  │   ├────────────┤  └──────────┘  └─────────┘
   └────────┘ └────────┘   │app/svc:    │
                            │amocrm,rag, │
        ┌────────┐          │sales,woo   │
        │Widget  │          └────────────┘
        │(public │
        │HTTP)   │     ┌────────────┐
        └────────┘     │Claude      │
                       │Bridge      │
        ┌────────┐     │(subprocess)│
        │Admin   │     └────────────┘
        │Panel   │
        │(JWT)   │
        └────────┘

Механизмы связи

Связь	Механизм	Файлы
Orchestrator → DB	Импорт синглтонов из db/integration.py + прямой AsyncSessionLocal	orchestrator.py:85-99, 3704, 3752, 3994
Routers → DB	Смесь: одни через менеджеры, другие через прямой AsyncSessionLocal	chat.py:18 vs audit.py:13
Routers → Services	ServiceContainer через get_container() или Depends()	app/dependencies.py
Routers → Bot managers	Прямой импорт глобальных синглтонов	from multi_bot_manager import multi_bot_manager
TG/WA Bot → Orchestrator	HTTP API через LLMRouter (httpx + BOT_INTERNAL_TOKEN JWT)	telegram_bot/services/llm_router.py
Bot → Config	Env vars + JSON в /tmp + HTTP fallback	multi_bot_manager.py:111-150
Widget → Orchestrator	Public HTTP endpoints (без auth) в orchestrator.py	orchestrator.py:3648-4040
Admin Panel → Orchestrator	JWT auth, HTTP REST + SSE	admin/src/api/*.ts
Bridge → Orchestrator	Subprocess, OpenAI-compatible API	bridge_manager.py

Data flow

TELEGRAM/WHATSAPP           WIDGET                    ADMIN PANEL
 ↓                           ↓                          ↓
Message handler          POST /widget/session       POST /admin/chat/
 ↓                           ↓                     sessions/{id}/stream
Session store (память)   Session store (DB)              ↓
 ↓                           ↓                     Session (DB)
LLMRouter.chat_stream()  orchestrator.py widget ep       ↓
 ↓                           ↓                     chat.py streaming
POST /admin/chat/        LLM selection (дубль!)     LLM selection
sessions/{id}/stream     RAG injection              RAG injection
 ↓                           ↓                          ↓
        ───────── CloudLLMService / vLLM ─────────
                         ↓
                   SSE response

---

2. Выявленные проблемы

P1 — Операционные риски (влияют на uptime)

2.1. Нет мониторинга подпроцессов ботов

• Где: multi_bot_manager.py, whatsapp_manager.py
• Суть: Бот-подпроцесс падает — оркестратор не знает. process.poll() проверяется только при API-вызове /status, не проактивно.
• Риск: Пользователи TG/WA получают тишину. Нет авторестарта.

2.2. Нет graceful shutdown

• Где: orchestrator.py:1156-1161
• Суть: При shutdown — только shutdown_database(). Боты НЕ останавливаются (start_new_session=True). Background tasks НЕ отменяются. Задачи _cleanup_expired_sessions и _periodic_vacuum запущены через create_task() без сохранения reference.
• Риск: Orphaned процессы, дубли ботов при рестарте.

2.3. Потеря сессий ботов при крэше

• Где: telegram_bot/services/session_store.py, whatsapp_bot/services/session_store.py
• Суть: TG и WA боты хранят историю разговоров только в памяти. Крэш/рестарт = полная потеря контекста.
• Нюанс: Боты уже создают сессии в оркестраторе через _ensure_session(), т.е. сообщения дублируются в DB. Но бот при рестарте не восстанавливает из DB — создаёт новые сессии.

---

P2 — Архитектурный долг (усложняет развитие)

2.4. God Object — orchestrator.py (4100 строк)

• Суть: Совмещает: инициализацию сервисов, ~100 legacy эндпоинтов, widget endpoints (~300 строк), background tasks, helper functions.
• Проблема: Widget-логика (LLM selection, RAG injection, amoCRM lead creation) дублирует chat.py.

2.5. Два паттерна доступа к БД

Через менеджеры (@retry_on_busy)	Прямой AsyncSessionLocal (без retry)
chat.py, telegram.py, whatsapp.py, faq.py, llm.py, amocrm.py, wiki_rag.py, kanban.py, workspace.py, auth.py, roles.py, woocommerce.py, claude_code.py, backup.py	audit.py, usage.py, bot_sales.py, legal.py, github_webhook.py + orchestrator.py (3 места)

8 точек доступа обходят менеджеры → нет retry, нет единообразной обработки ошибок.

2.6. ServiceContainer покрывает только hardware-сервисы

• В контейнере: TTS, STT, LLM, GSM, WikiRAG.
• Всё остальное (30+ DB-менеджеров, bot managers, bridge) — глобальные синглтоны через прямой import.
• Результат: два механизма DI — Depends(get_llm_service) vs from db.integration import async_chat_manager.

2.7. Дублирование LLM backend selection

• app/routers/chat.py:624-697 — для admin/bot сессий
• orchestrator.py:3880-3892 — для widget сессий
• Одна и та же логика: parse cloud:{provider_id}, load provider, fallback chain.

---

P3 — Средний приоритет

2.8. Фрагментация сервисного слоя

• Root (12 файлов): cloud_llm, voice, stt, managers
• app/services/ (8+ файлов): amocrm, rag, sales, woo
• Нет документированного критерия разделения.

2.9. Инкогерентность кешей

Кеш	Файл	Тип	Инвалидация
SessionCache (jti→user)	auth_manager.py	in-memory dict	Ручная при revoke
PermissionsCache (role→perms)	auth_manager.py	in-memory dict	Ручная при role update
MemberRoleCache (user,ws→role)	auth_manager.py	in-memory dict	Ручная при role change
FAQ в CloudLLMService	cloud_llm_service.py	instance var	При явном reload
TTS streaming	orchestrator.py	dict + Lock	LRU
Redis (amocrm pipelines/leads)	db/redis_client.py	Redis	TTL

Нет единой стратегии. Пропуск ручного invalidate = stale data.

2.10. Config из трёх источников

• .env → os.getenv() повсюду
• DB (config table, provider configs, bot configs)
• Subprocess env (snapshot at spawn time, не обновляется)

2.11. Отдельные sales DB в подпроцессах

• telegram_bot/sales/database.py → data/sales.db
• whatsapp_bot/sales/database.py → data/wa_sales_{id}.db
• Вне основной DB, нет единого view на воронку.

---

3. Как должно быть правильно (рекомендации)

Tier 1 — Критичные (uptime)

#	Рекомендация	Объём	Суть
R1	Health monitor подпроцессов	S (~50 строк)	Background task: poll process.poll() каждые 30с. Если dead + auto_start=True → рестарт. Логирование.
R2	Graceful shutdown	S (~30 строк)	В shutdown_event(): stop all bots → stop bridge → cancel tasks → close DB. Сохранять Task references.
R3	Bot sessions из DB	L (рефакторинг)	Бот при рестарте восстанавливает сессии из orchestrator API. Убрать дублирование in-memory ↔ DB.

Tier 2 — Высокий (архитектура)

#	Рекомендация	Объём	Суть
R4	Widget → app/routers/widget.py	M (move)	Вынести ~300 строк widget endpoints из orchestrator.py. Заодно переиспользовать LLM selection из chat.py.
R5	Консолидировать DB-доступ	M	5 роутеров (audit, usage, bot_sales, legal, github_webhook) + orchestrator.py → через менеджеры. Все получат @retry_on_busy.
R6	Shared LLM resolution	S (~50 строк)	Extract resolve_llm_backend() → использовать в chat.py и widget router.

Tier 3 — Средний

#	Рекомендация	Объём	Суть
R7	Реестр background tasks	S	TaskRegistry(name→Task). Cancel all in shutdown. Show in /health.
R8	Cache invalidation events	M	Event-based invalidation вместо ручных вызовов.
R9	Merge sales DB	L	Перенести sales tables в secretary.db. Унифицировать миграции.

Tier 4 — Low priority

#	Рекомендация	Объём
R10	Документировать правило root/ vs app/services/	Текст
R11	Hot-reload конфига ботов (без рестарта)	M

---

4. Рекомендуемый порядок

R2 (shutdown)  ──→  R1 (health monitor)  ──→  R7 (task registry)
         независимо от:
R4 (widget router)  ──→  R6 (shared LLM resolution)
         независимо от:
R5 (DB consolidation)
         потом:
R3 (bot sessions)  ──→  R9 (sales DB merge)

• R1+R2 — один PR, минимальный риск
• R4+R6 — второй PR, чистый рефакторинг (move + extract)
• R5 — третий PR, каждый роутер отдельным коммитом

S = 1-2 часа, M = полдня, L = день+

[shikhalev]

Дополнение: послойный анализ разделения доменов

Анализ показал, что функциональные подсистемы разделены по вертикали (роутеры + репозитории), но сливаются по горизонтали (модели, менеджеры, оркестратор).

Разделение по слоям

Слой	Файлов	Разделение	Проблема
Роутеры (app/routers/)	26	ЧИСТО	0 кросс-импортов между роутерами
Репозитории (db/repositories/)	45	ЧИСТО	Импорт только BaseRepository
Модели (db/models.py)	1 файл, 55 классов	СМЕШАНО	Все домены в одном файле. Кросс-доменные FK (ClaudeCodeSession → ChatSession + KanbanTask)
Менеджеры (db/integration.py)	1 файл, 28 классов, 2688 строк	СМЕШАНО	Невозможно импортировать менеджер одного домена без загрузки всех 28
Оркестратор (orchestrator.py)	1 файл, ~4100 строк	СИЛЬНО СМЕШАНО	Startup всех доменов + ~100 legacy endpoints дублирующих роутеры

Текущая структура (горизонтальная)

db/models.py          ← 55 моделей ВСЕХ доменов
db/repositories/      ← 45 файлов (ЧИСТО)
db/integration.py     ← 28 менеджеров ВСЕХ доменов
app/routers/          ← 26 файлов (ЧИСТО)
orchestrator.py       ← startup/legacy ДЛЯ ВСЕХ

Альтернатива (вертикальная, не предлагается к реализации — для понимания)

domains/
  chat/
    models.py, repository.py, manager.py, router.py
  kanban/
    models.py, repository.py, manager.py, router.py
  crm/
    models.py, repository.py, manager.py, router.py
  ...
shared/
  knowledge/     ← общий ресурс, используется chat, kanban, crm, woo
  auth/          ← общий ресурс, используется везде

Knowledge/RAG — скрытый общий ресурс

Knowledge Collections импортируются в 4+ доменах:

• chat.py — RAG context injection в LLM
• kanban.py — связь задач с базой знаний
• amocrm.py — CRM dataset sync
• woocommerce.py — product catalog sync

Это корректная архитектура (shared infrastructure), но связь неявная — нигде не задокументирован статус knowledge как "shared module".

Практическое следствие

Текущее горизонтальное разделение:

• Плюс: Простота навигации (все модели — в models.py, все роутеры — в routers/)
• Минус: Файлы-монолиты (models.py 3667 строк, integration.py 2688 строк) с нулевой изоляцией доменов
• Минус: import db.integration загружает ВСЕ 28 менеджеров, даже если нужен один
• Минус: Orchestrator — единая точка связывания, невозможно стартовать один домен без всех

Переход к вертикальным модулям — масштабный рефакторинг (не рекомендуется как отдельная задача). Но полезно учитывать при создании новых доменов: оформлять как пакет, а не дописывать в общие файлы.

[shikhalev]

Целевая архитектура: модульная декомпозиция

Описание желаемой архитектуры безотносительно текущей реализации. Не план миграции, а целевое состояние.

---

Принципы

1. Каждый домен = пакет с собственными models, repository, service, router
2. Зависимости однонаправленные — нижние слои не знают о верхних
3. Взаимодействие через интерфейсы — модули зависят от протоколов, не от реализаций
4. Нет файлов-монолитов — ни один файл не отвечает за все домены сразу
5. Deployment mode — переключение на уровне модулей, не if-statements

---

1. Каталог модулей

modules/
├── core/           ← Фундамент (DB, auth, config, events, health)
├── knowledge/      ← RAG, wiki, коллекции, эмбеддинги
├── llm/            ← LLM-провайдеры, генерация, fallback
├── chat/           ← Сессии, сообщения, стриминг, бранчинг
├── channels/
│   ├── telegram/   ← Telegram бот-менеджер + подпроцесс
│   ├── whatsapp/   ← WhatsApp бот-менеджер + подпроцесс
│   └── widget/     ← Web-виджет, lead tracking
├── crm/            ← amoCRM (OAuth, leads, contacts, inbox)
├── ecommerce/      ← WooCommerce (products, orders)
├── sales/          ← Воронки, сегменты, платежи
├── kanban/         ← Проекты, задачи, roadmap
├── claude_code/    ← WebSocket CLI, сессии, проекты
├── speech/         ← TTS/STT/Voice (local-only)
├── telephony/      ← GSM/SIM (local-only)
├── monitoring/     ← Audit, usage, system health
└── admin/          ← Backup, GDPR, settings, FAQ

---

2. Структура каждого модуля

Каждый модуль — Python-пакет со стандартной структурой:

modules/{domain}/
    __init__.py      # Публичный API модуля (экспорты)
    models.py        # SQLAlchemy модели ТОЛЬКО этого домена
    repository.py    # Репозиторий (данные)
    service.py       # Бизнес-логика
    router.py        # FastAPI роутер
    events.py        # Определения событий (dataclasses)
    schemas.py       # Pydantic модели запросов/ответов
    tasks.py         # Background tasks (если есть)

Модуль экспортирует через __init__.py:

• Service class (основной интерфейс)
• Event dataclasses (для подписки другими модулями)
• Router (для регистрации в приложении)

Модуль НЕ экспортирует:

• Репозитории (внутренняя деталь)
• SQLAlchemy модели напрямую (только через service API)

---

3. Модуль core — фундамент

core/
    database.py      # Engine, session factory, init/shutdown
    auth/
        models.py    # User, Role, RolePermission, UserSession, WorkspaceMember, UserIdentity
        service.py   # AuthService: login, JWT, RBAC checks, session management
        guards.py    # require_permission(), get_current_user(), workspace_context()
        cache.py     # SessionCache, PermissionsCache, MemberRoleCache
        router.py    # /admin/auth/*, /admin/roles/*, /admin/workspace/*
    config.py        # Единый ConfigService: .env + DB, приоритет DB > env
    events.py        # EventBus (in-process pub/sub)
    cache.py         # CacheManager: in-memory + Redis, unified invalidation
    health.py        # HealthRegistry: каждый модуль регистрирует свой health check
    tasks.py         # TaskRegistry: named background tasks, cancel_all()
    base.py          # BaseRepository, BaseService

Правила:

• core не зависит ни от одного модуля
• Все модули зависят от core
• Auth — часть core (нужен всем)

EventBus — простой in-process pub/sub:

class EventBus:
    async def publish(self, event: BaseEvent) -> None: ...
    def subscribe(self, event_type: type[BaseEvent], handler: Callable) -> None: ...

---

4. Граф зависимостей

                        ┌──────────┐
                        │   core   │
                        │ db, auth,│
                        │ config,  │
                        │ events   │
                        └────┬─────┘
                 ┌───────────┼───────────────┐
                 │           │               │
           ┌─────┴─────┐ ┌──┴──┐    ┌───────┴───────┐
           │ knowledge  │ │ llm │    │    speech      │
           │ RAG, wiki  │ │     │    │   TTS/STT      │
           │ collections│ │     │    │  (local-only)   │
           └─────┬──────┘ └──┬──┘    └───────────────┘
                 │           │
                 └─────┬─────┘
                       │
                 ┌─────┴─────┐
                 │    chat    │
                 │ sessions,  │
                 │ streaming  │
                 └─────┬──────┘
           ┌───────────┼───────────────┐
           │           │               │
     ┌─────┴─────┐ ┌──┴──────┐  ┌─────┴──────┐
     │ channels   │ │ kanban  │  │claude_code │
     │ TG/WA/     │ │         │  │            │
     │ Widget     │ └─────────┘  └────────────┘
     └─────┬──────┘
           │
     ┌─────┴─────┐
     │   sales    │
     └────────────┘

     ┌─────────┐  ┌──────────┐
     │   crm   │  │ecommerce │
     │ amoCRM  │  │ WooCom.  │
     └────┬────┘  └────┬─────┘
          └──────┬─────┘
                 │
           зависят от:
           core + knowledge + chat

Таблица зависимостей

Модуль	Зависит от	Что берёт
knowledge	core	DB, auth guards
llm	core	DB (provider configs), config
speech	core	DB (presets), config
chat	core, knowledge, llm	auth, RAG-поиск, LLM-генерация
channels/telegram	core, chat	auth (internal tokens), chat API
channels/whatsapp	core, chat	auth (internal tokens), chat API
channels/widget	core, chat	chat API, public endpoints
sales	core, channels	подписчики, доставка сообщений
kanban	core	DB, auth
claude_code	core	DB, auth, WebSocket
crm	core, knowledge, chat	dataset sync, session linking
ecommerce	core, knowledge	dataset sync
monitoring	core	DB, health registry
admin	core	DB, backup
telephony	core	DB, config

Запрещённые зависимости:

• core → любой модуль
• knowledge → chat, channels, crm
• llm → chat, channels
• chat → channels, crm, kanban
• kanban → chat (связь через события, не импорт)

---

5. Протоколы взаимодействия

5A. Синхронные интерфейсы (вызовы внутри процесса)

Каждый модуль экспортирует service с типизированным API:

# knowledge/__init__.py
class KnowledgeService(Protocol):
    async def search(self, query: str, collection_ids: list[int] | None,
                     top_k: int = 3, max_chars: int = 2500) -> list[SearchResult]: ...
    async def search_multi(self, query: str, collection_ids: list[int],
                           top_k: int = 3) -> list[SearchResult]: ...
    async def get_collections(self, enabled_only: bool = True) -> list[Collection]: ...
    async def sync_documents(self, collection_id: int, base_dir: str) -> SyncResult: ...

# llm/__init__.py
class LLMService(Protocol):
    async def generate(self, messages: list[Message], config: LLMConfig) -> str: ...
    async def stream(self, messages: list[Message], config: LLMConfig) -> AsyncIterator[str]: ...
    async def resolve_backend(self, backend_id: str) -> LLMProvider: ...

# chat/__init__.py
class ChatService(Protocol):
    async def create_session(self, source: str, source_id: str | None,
                             system_prompt: str | None, owner_id: int | None,
                             workspace_id: int) -> Session: ...
    async def send_message(self, session_id: str, content: str,
                           llm_override: LLMConfig | None = None) -> Message: ...
    async def stream_message(self, session_id: str, content: str,
                             llm_override: LLMConfig | None = None) -> AsyncIterator[StreamChunk]: ...
    async def get_session(self, session_id: str) -> Session | None: ...
    async def get_history(self, session_id: str) -> list[Message]: ...

Chat внутри себя вызывает Knowledge и LLM:

# chat/service.py
class ChatServiceImpl:
    def __init__(self, knowledge: KnowledgeService, llm: LLMService):
        self.knowledge = knowledge
        self.llm = llm

    async def stream_message(self, session_id, content, llm_override=None):
        session = await self._get_session(session_id)
        rag_context = await self.knowledge.search(content, session.collection_ids)
        prompt = self._build_prompt(session.system_prompt, rag_context)
        messages = await self._build_message_list(session_id, content, prompt)
        backend = await self.llm.resolve_backend(llm_override or session.llm_backend)
        async for chunk in self.llm.stream(messages, backend):
            yield chunk

5B. Асинхронные события (fire-and-forget)

Модули публикуют события через EventBus. Другие модули подписываются. Нет прямых зависимостей.

# channels/widget/events.py
@dataclass
class WidgetSessionCreated:
    session_id: str
    widget_instance_id: str
    visitor_metadata: dict

@dataclass
class WidgetMessageSent:
    session_id: str
    content: str
    is_first: bool

# crm/service.py — подписывается
class CRMService:
    def setup_events(self, bus: EventBus):
        bus.subscribe(WidgetSessionCreated, self._on_widget_session)
        bus.subscribe(WidgetMessageSent, self._on_widget_message)

    async def _on_widget_session(self, event: WidgetSessionCreated):
        """Создать lead в amoCRM при создании виджет-сессии."""
        ...

Какие события нужны:

Событие	Публикует	Подписчики
UserRoleChanged	core/auth	core/cache (invalidate)
SessionRevoked	core/auth	core/cache (invalidate)
WidgetSessionCreated	channels/widget	crm (create lead)
WidgetMessageSent	channels/widget	crm (append note)
WidgetContactSubmitted	channels/widget	crm (link contact)
BotProcessDied	channels/telegram, /whatsapp	monitoring (alert), self (auto-restart)
KnowledgeUpdated	knowledge	llm (reload FAQ cache)
ConfigChanged	core/config	affected modules (reload)
DatasetSynced	crm, ecommerce	knowledge (reindex)

5C. HTTP-контракты (кросс-процессные)

Бот-подпроцессы общаются с основным процессом только через HTTP. Контракт:

# Бот → Основной процесс
POST /internal/chat/sessions                          # Создать сессию
POST /internal/chat/sessions/{id}/stream              # Отправить сообщение (SSE)
GET  /internal/chat/sessions/{id}/history             # Получить историю (при рестарте)
POST /internal/bot/heartbeat                          # Health ping каждые 30с
GET  /internal/bot/config/{instance_id}               # Получить/обновить конфиг

# Авторизация: Bearer token (internal JWT, role=bot)
# Prefix /internal/ отделяет от /admin/ и /widget/

Принципы:

• Боты НЕ импортируют DB-модули основного процесса
• Боты НЕ обращаются к SQLite напрямую
• Вся персистентность — через API
• Config polling: бот проверяет конфиг через API раз в N минут

---

6. Композиция приложения (startup)

Вместо одного startup event на 300 строк — каждый модуль регистрирует свой lifecycle:

# app.py (замена orchestrator.py, ~50 строк)
from core import create_app, EventBus, HealthRegistry, TaskRegistry
from modules import knowledge, llm, chat, channels, crm, ...

app = create_app()

# Фаза 1: Инициализация core
db = await init_database()
bus = EventBus()
health = HealthRegistry()
tasks = TaskRegistry()

# Фаза 2: Создание сервисов (порядок = граф зависимостей)
knowledge_svc = knowledge.create_service(db)
llm_svc = llm.create_service(db, config)
chat_svc = chat.create_service(db, knowledge_svc, llm_svc)

# Фаза 3: Регистрация роутеров
app.include_router(knowledge.router)
app.include_router(llm.router)
app.include_router(chat.router)

# Фаза 4: Подписка на события
crm_svc.setup_events(bus)
monitoring_svc.setup_events(bus)

# Фаза 5: Запуск background tasks
tasks.register("session_cleanup", chat_svc.periodic_cleanup, interval=3600)
tasks.register("vacuum", db.periodic_vacuum, interval=7*24*3600, initial_delay=24*3600)
tasks.register("bot_health", channels.health_monitor, interval=30)

# Shutdown
@app.on_event("shutdown")
async def shutdown():
    await tasks.cancel_all()
    await channels.stop_all_bots()
    await db.close()

---

7. Deployment modes

Вместо if DEPLOYMENT_MODE != "cloud": — модули просто не загружаются:

# app.py
MODULES = {
    "full":  [knowledge, llm, chat, channels, crm, ecommerce, sales,
              kanban, claude_code, speech, telephony, monitoring, admin],
    "cloud": [knowledge, llm, chat, channels, crm, ecommerce, sales,
              kanban, claude_code, monitoring, admin],
    "local": [knowledge, llm, chat, channels, crm, ecommerce, sales,
              kanban, claude_code, speech, telephony, monitoring, admin],
}

for module in MODULES[DEPLOYMENT_MODE]:
    svc = module.create_service(db, **deps)
    app.include_router(module.router)

speech и telephony просто не загружаются в cloud mode. Никаких if-statements внутри других модулей.

Health check автоматически показывает только загруженные модули.

Роутер /admin/deployment-mode возвращает список загруженных модулей → фронтенд скрывает ненужные вкладки.

---

8. Cross-cutting concerns

Кеширование

Единый CacheManager с namespace:

cache.get("auth:session:{jti}")
cache.get("knowledge:faq:{workspace_id}")
cache.invalidate_pattern("auth:session:*")  # при mass-revoke

Слои: L1 in-memory (TTL) → L2 Redis (optional). Инвалидация через EventBus: при UserRoleChanged → cache.invalidate_pattern("auth:permissions:{role}").

Кросс-доменные FK

Слабые связи (не через FK, а через ID + event):

# claude_code/models.py
class ClaudeCodeSession:
    chat_session_id: str | None = None    # Просто строка, не FK
    kanban_task_id: int | None = None     # Просто int, не FK

# Целостность — через events:
# При удалении ChatSession → publish ChatSessionDeleted
# claude_code подписывается → обнуляет chat_session_id

Конфигурация

Единый источник: DB (таблица config). .env — только для секретов и bootstrap (DB URL, JWT secret). Модули объявляют свои config-ключи:

# llm/config.py
class LLMConfig(ModuleConfig):
    default_backend: str = "vllm"
    max_tokens: int = 4096

---

9. Итоговая диаграмма

┌─────────────────────────────────────────────────────────┐
│                    app.py (~50 строк)                    │
│          Композиция: загрузка модулей, wiring            │
└────────────────────────┬────────────────────────────────┘
                         │
        ┌────────────────┼────────────────────┐
        │                │                    │
   ┌────┴────┐    ┌──────┴──────┐     ┌───────┴───────┐
   │ Events  │    │   Health    │     │    Tasks      │
   │  Bus    │    │  Registry   │     │   Registry    │
   └────┬────┘    └──────┬──────┘     └───────┬───────┘
        │                │                    │
        └────────────────┼────────────────────┘
                         │
        ┌────────────────┼────────────────────┐
        │                │                    │
  ┌─────┴────┐    ┌──────┴─────┐      ┌──────┴──────┐
  │knowledge │    │    llm     │      │   speech    │
  │ search() │    │ generate() │      │ synthesize()│
  │ sync()   │    │ stream()   │      │ transcribe()│
  └─────┬────┘    └──────┬─────┘      └─────────────┘
        │                │
        └───────┬────────┘
                │
         ┌──────┴──────┐
         │    chat      │
         │send_message()│
         │  stream()    │
         └──────┬───────┘
     ┌──────────┼──────────────┐
     │          │              │
┌────┴───┐ ┌───┴────┐  ┌──────┴──────┐
│channels│ │ kanban  │  │ claude_code │
│TG/WA/  │ │        │  │             │
│Widget  │ └────────┘  └─────────────┘
└────┬───┘
     │
┌────┴───┐   ┌──────────┐
│ sales  │   │crm / ecom│
└────────┘   └──────────┘

Стрелки = зависимости (сверху вниз = допустимо)
Горизонтальные связи = через EventBus

---

10. Сравнение с текущим состоянием

Аспект	Сейчас	Целевое
Точка входа	orchestrator.py (4100 строк)	app.py (~50 строк)
Модели	1 файл, 55 классов	По файлу на модуль
Менеджеры	1 файл, 28 классов	service.py в каждом модуле
DI	ServiceContainer (только hardware) + глобальные синглтоны	Explicit constructor injection
Кросс-модульная связь	Прямой импорт	Protocol interfaces + EventBus
Background tasks	fire-and-forget create_task()	TaskRegistry с cancel_all()
Кеширование	5 независимых кешей	Единый CacheManager + event invalidation
Deploy modes	if-statements	Модули не загружаются
Bot ↔ Main	Прямой DB import + HTTP	Только HTTP (/internal/ API)
Shutdown	Только DB close	Tasks → Bots → Bridge → DB