C4: Containers

Обзор архитектуры

Думатель построен на микросервисной архитектуре с event-driven взаимодействием через NATS JetStream. Все сервисы развёрнуты в Kubernetes (Selectel MKS) и управляются через ArgoCD (GitOps).

Диаграмма контейнеров

Исходный код диаграммы:

graph TB
    user["👤 Пользователь"]

    user -->|HTTPS| seadragon

    subgraph frontend ["Frontend"]
        seadragon["Seadragon<br/><i>Next.js 15, React 18, TS</i><br/>AI SDK 5.0, Zustand"]
        coral["Coral<br/><i>@coral/ui — UI-библиотека</i>"]
        seadragon -.-> coral
    end

    seadragon -->|REST API| sprut
    seadragon -->|SSE стриминг| nats

    subgraph api ["API Layer"]
        sprut["Sprut<br/><i>Python 3.14, FastAPI</i><br/>API Gateway — 15+ endpoints"]
    end

    sprut -->|asyncpg| postgres
    sprut -->|pymilvus| milvus
    sprut -->|Publish tasks| nats
    sprut -->|Billing ops| doubloon
    sprut -->|Auth| keycloak["Keycloak<br/><i>SSO / OIDC</i>"]

    subgraph business ["Business Services"]
        doubloon["Doubloon<br/><i>Billing, Tinkoff API</i>"]
        chronograf["Chronograf<br/><i>Task Scheduler</i>"]
        anchor["Anchor<br/><i>Payment status</i>"]
        shark["Shark<br/><i>Scheduled worker</i>"]
        convictfish["ConvictFish<br/><i>Bitrix CRM sync</i>"]
        kraken["Kraken<br/><i>Wolfram Alpha</i>"]
        descent["Descent<br/><i>Yandex upload</i>"]
        bilge["Bilge<br/><i>Subscriptions</i>"]
        gull["Gull<br/><i>Email + Bitrix CRM</i>"]
        sealayers["Sealayers<br/><i>ML Classification</i>"]
    end

    subgraph rag ["RAG / AI Pipeline"]
        amigofish["Amigofish<br/><i>AI Query Worker</i><br/>LangGraph, LLM APIs"]
        anglerfish["Anglerfish<br/><i>Doc Indexing</i><br/>LlamaIndex"]
        krill["Krill<br/><i>PDF + OCR</i>"]
    end

    nats -->|AI tasks| amigofish
    nats -->|Index tasks| anglerfish
    nats -->|PDF tasks| krill
    nats -->|Email tasks| gull
    nats -->|Billing tasks| bilge
    nats -->|Shark tasks| shark
    nats -->|Upload tasks| descent
    nats -->|ConvictFish tasks| convictfish
    chronograf -->|Publish scheduled| nats
    amigofish -->|FrontProducer| nats
    anglerfish -->|Store embeddings| milvus
    doubloon -->|Payments| tinkoff["Tinkoff API"]
    gull -->|CRM| bitrix["Битрикс 24"]

    subgraph data ["Data Layer"]
        postgres[("PostgreSQL 17<br/><i>OLTP — psdot models</i>")]
        milvus[("Milvus 2.5.14<br/><i>Vectors — BM25 + dense</i>")]
        redis[("Redis 8.2.1<br/><i>Cache</i>")]
        minio[("MinIO<br/><i>Object Storage</i>")]
        nats["NATS JetStream 2.11<br/><i>Message Broker</i>"]
    end

    style frontend fill:#4a7eb5,stroke:#2d5f8a,color:#fff
    style api fill:#5a9e6f,stroke:#3a7a4f,color:#fff
    style business fill:#8b6db8,stroke:#6a4f9a,color:#fff
    style rag fill:#c47c2b,stroke:#9a5f1a,color:#fff
    style data fill:#5b9dad,stroke:#3a7a8a,color:#fff

Описание контейнеров

Frontend

Контейнер	Технология	Назначение
Seadragon	Next.js 15, React 18, TypeScript, AI SDK 5.0, Zustand, TanStack, NextAuth 5	Основное web-приложение. Чат-интерфейс с LLM, потоковая обработка через AI SDK и NATS. Tailwind + shadcn/ui
Coral	React, TypeScript, Storybook	Монорепозиторий UI-компонентов (@coral/ui). Переиспользуемые примитивы на базе Radix UI + Tailwind

API Layer

Контейнер	Технология	Назначение
Sprut	Python 3.14, FastAPI, asyncpg, Milvus, Keycloak	API Gateway — центральная точка входа. 15+ роутеров: auth, billing, chat, documents, projects, notifications

Business Services

Контейнер	Технология	Назначение
Doubloon	Python, FastAPI, Tinkoff API	Биллинг и платежи. Управление балансом, тарифами, транзакциями
Chronograf	Python, NATS Producer	Планировщик задач. Периодические задачи, расписания
Anchor	Python, orker, Tinkoff API	Обработка статусов платежей
Shark	Python, orker	Scheduled worker
ConvictFish	Python, orker	Daily Bitrix CRM sync worker
Kraken	Python, FastAPI	Stateless математический вычислитель через Wolfram Alpha API
Descent	Python, orker	Загрузка файлов в Yandex
Bilge	Python, orker	Управление жизненным циклом подписок
Gull	Python, orker, Bitrix, SMTP	Email-сервис. Отправка писем, интеграция с Bitrix CRM
Sealayers	Python, FastAPI	Сервис классификации запросов

RAG / AI Pipeline

Контейнер	Технология	Назначение
Amigofish	Python, orker, LLM APIs (OpenAI/Claude), Milvus	Обработка AI-запросов. Мультиагентная система (LangGraph) с RAG + web-search
Anglerfish	Python, orker, LlamaIndex, Milvus	ETL-индексирование: документы → vectorized chunks → Milvus. Поддержка PDF, изображений, таблиц
Krill	Python, orker, OCR	Парсинг PDF-документов и OCR

Data Layer

Контейнер	Технология	Порт	Назначение
PostgreSQL	PostgreSQL 17	5432	Основная OLTP БД. Управляется через psdot (sqlalchemy-models-and-migrations)
Milvus	Milvus 2.5.14	19530	Векторная БД. Гибридный поиск: BM25 + dense + RRF
Redis	Redis 8.2.1	6379	Application cache (aiocache)
MinIO	MinIO	9000	S3-совместимое объектное хранилище файлов
NATS JetStream	NATS 2.11.8	4222	Message broker для асинхронного взаимодействия + AI-стриминг
etcd	etcd 3.5.18	—	Distributed config (для Milvus)
Yandex Object Storage	Yandex Cloud	—	Хранение пользовательских файлов

Shared Libraries

Библиотека	Назначение
psdot (sqlalchemy-models-and-migrations)	Единая точка истины для ORM-моделей и Alembic-миграций всех сервисов
orker	NATS worker framework — async framework для всех Python-воркеров с retry, error handling, DB integration
@coral/ui	Переиспользуемые React-компоненты с Radix UI и Tailwind

Обзор архитектуры​

Диаграмма контейнеров​

Описание контейнеров​

Frontend​

API Layer​

Business Services​

RAG / AI Pipeline​

Data Layer​

Shared Libraries​