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

На этой странице описана архитектура платформы Univex. Диаграммы охватывают два уровня детализации: контекст системы (кто использует платформу и какие внешние системы с ней взаимодействуют) и контейнеры (внутренние сервисы, хранилища данных и их связи).

Уровень 1 — Контекст системы¶

Диаграмма показывает Univex как единую систему в окружении внешних акторов и сторонних интеграций.

graph TD
    User["👤 Пользователь\n(Фронтенд / Мобильное приложение)"]
    Admin["👤 Администратор\n(Административная панель)"]

    subgraph Univex ["Платформа Univex"]
        GW["gateway\nHTTP Fiber v2"]
        AGW["admin-gateway\nHTTP Fiber v2 + Casbin"]
        ExAPI["Exchange HTTP API\nEcho REST"]
    end

    Blockchain["🔗 Блокчейн-сети\nBTC / ETH / TRON"]
    Sumsub["Sumsub\nKYC/KYB"]
    Elliptic["Elliptic\nAML"]
    SMTP["SMTP\nEmail-сервер"]
    SNS["AWS SNS / Telegram\nSMS-доставка"]

    User -->|"HTTPS"| GW
    User -->|"HTTPS / WSS"| ExAPI
    Admin -->|"HTTPS"| AGW

    GW -.->|"gRPC"| Univex
    AGW -.->|"gRPC"| Univex

    ExAPI -->|"RPC / JSON-RPC"| Blockchain
    Univex -->|"HTTPS API"| Sumsub
    Univex -->|"HTTPS API"| Elliptic
    Univex -->|"SMTP"| SMTP
    Univex -->|"AWS SDK"| SNS

Уровень 2 — Контейнеры¶

Диаграмма раскрывает внутреннюю структуру платформы: все сервисы обоих репозиториев, хранилища данных и каналы взаимодействия.

graph TD
    User["👤 Пользователь"]
    Admin["👤 Администратор"]

    %% Точки входа
    GW["gateway\nFiber v2 HTTP"]
    AGW["admin-gateway\nFiber v2 + Casbin RBAC"]

    %% Монорепозиторий — бизнес-сервисы
    UID["univex-id\ngRPC · 95+ RPC"]
    LEDGER["ledger\ngRPC · 26 RPC"]
    P2P["p2p\ngRPC · 43 RPC"]
    EI["exchange-integration\ngRPC · 60 RPC"]
    TA["trades-aggregator\ngRPC streaming · 2 RPC"]
    EMAIL["email\ngRPC + AWS SQS\nSMTP"]
    SMS["sms-gate\ngRPC + AWS SQS\nSNS + Telegram fallback"]
    SUMSUB["sumsub-integration\ngRPC + Fiber webhooks"]

    %% Exchange Engine
    subgraph Engine ["Exchange Engine (Go 1.25)"]
        ExAPI["Exchange HTTP API\nEcho · /api/v1/"]
        AdminGRPC["Admin gRPC Service"]
        Orderbook["Orderbook Engine"]
        HM["hotmanager\nbtc / evm / tron"]
        TS["topupscan\nbtc / evm / tron\n+ aml-poller + elliptic_check\n+ refund-processor"]
        TXP["txprocessor\nbtc / evm / tron"]
    end

    %% Хранилища данных
    PG[("PostgreSQL\n10 баз данных\n+ PgBouncer")]
    REDIS[("Redis / Valkey\nКэш · Сессии · pub/sub")]
    TEMPORAL[("Temporal.io\nWorkflow Orchestration")]
    S3[("S3-совместимое\nObject Storage")]
    SQS[("AWS SQS\nОчереди сообщений")]

    %% Внешние системы
    Blockchain["🔗 BTC / ETH / TRON"]
    SumsubExt["Sumsub\nKYC/KYB"]
    EllipticExt["Elliptic\nAML"]
    SMTPExt["SMTP-сервер"]
    SNSExt["AWS SNS\nTelegram"]

    %% Пользователи → точки входа
    User -->|"HTTPS"| GW
    User -->|"HTTPS / WSS"| ExAPI
    Admin -->|"HTTPS"| AGW

    %% gateway → сервисы монорепозитория
    GW -->|"gRPC"| UID
    GW -->|"gRPC"| LEDGER
    GW -->|"gRPC"| P2P
    GW -->|"gRPC streaming"| TA

    %% admin-gateway → сервисы монорепозитория
    AGW -->|"gRPC"| UID
    AGW -->|"gRPC"| LEDGER
    AGW -->|"gRPC"| P2P
    AGW -->|"gRPC"| EI

    %% univex-id → зависимости
    UID -->|"gRPC"| EMAIL
    UID -->|"gRPC"| SMS
    UID -->|"gRPC"| SUMSUB
    UID -->|"gRPC"| EI
    UID -->|"gRPC"| LEDGER
    UID --- REDIS
    UID --- TEMPORAL

    %% p2p → зависимости
    P2P -->|"gRPC (подтверждения)"| UID
    P2P --- TEMPORAL

    %% ledger → зависимости
    LEDGER -->|"gRPC"| EI
    LEDGER --- TEMPORAL

    %% trades-aggregator → Exchange HTTP API
    TA -->|"HTTP REST"| ExAPI
    TA --- TEMPORAL

    %% exchange-integration → Admin gRPC
    EI -->|"gRPC"| AdminGRPC

    %% Exchange Engine внутренние связи
    ExAPI --- Orderbook
    AdminGRPC --- Orderbook

    %% Фоновые сервисы → блокчейн
    HM -->|"RPC"| Blockchain
    TS -->|"RPC"| Blockchain
    TXP -->|"RPC"| Blockchain

    %% Фоновые сервисы → AML
    TS -->|"HTTPS"| EllipticExt

    %% Хранилища
    UID --- PG
    LEDGER --- PG
    P2P --- PG
    EI --- PG
    TA --- PG
    EMAIL --- PG
    SMS --- PG
    Orderbook --- PG
    AdminGRPC --- PG

    UID --- S3
    SUMSUB -->|"HTTPS API"| SumsubExt
    EMAIL --- SQS
    SMS --- SQS
    SMS -->|"AWS SDK"| SNSExt
    SMS -->|"fallback"| SNSExt
    EMAIL -->|"SMTP"| SMTPExt

Описание взаимодействий¶

Пользовательский поток (торговля)¶

Пользователь аутентифицируется через gateway → univex-id (gRPC).
Торговые запросы направляются в Exchange HTTP API (/api/v1/).
Exchange HTTP API передаёт ордера в Orderbook Engine для матчинга.
Исполненные сделки сохраняются в PostgreSQL.
Обновления котировок транслируются через WebSocket в реальном времени.

Пользовательский поток (балансы и переводы)¶

Запросы на баланс, переводы и фиатные операции идут через gateway → ledger (gRPC).
ledger проксирует операции в exchange-integration → Admin gRPC → Exchange Engine.
Долгосрочные операции оркестрируются через Temporal.io с гарантированным выполнением.

P2P-поток¶

Запросы управления объявлениями и ордерами идут через gateway → p2p (gRPC).
p2p обращается к univex-id для верификации участников сделки.
State machine ордеров и споры управляются через Temporal.io workflows.

Административный поток¶

Оператор подключается к admin-gateway (Fiber v2 + Casbin RBAC).
Запросы проксируются к univex-id, ledger, p2p или exchange-integration в зависимости от маршрута.
exchange-integration транслирует вызовы к Admin gRPC Exchange Engine.

KYC / AML поток¶

Пользователь инициирует верификацию через univex-id.
univex-id вызывает sumsub-integration (gRPC) для получения токена доступа.
Документы сохраняются в S3-совместимом хранилище.
Sumsub отправляет webhook о терминальном статусе в sumsub-integration (Fiber HTTP handler).
AML-проверка транзакций выполняется через elliptic_check в составе topupscan (Exchange Engine).

Блокчейн-поток (депозиты и выводы)¶

topupscan (btc/evm/tron) непрерывно мониторит входящие транзакции.
При обнаружении депозита баланс обновляется в PostgreSQL через txprocessor.
hotmanager управляет горячими кошельками и подписывает исходящие транзакции.
Запросы на вывод проходят через Admin gRPC → txprocessor → Blockchain.

Уведомления¶

Сервисы монорепозитория вызывают email или sms-gate через gRPC.
Оба сервиса публикуют сообщения в AWS SQS для надёжной асинхронной доставки.
sms-gate использует AWS SNS как основной канал, Telegram — как fallback.
email доставляет письма через SMTP.

Инфраструктурные зависимости¶

Компонент	Используется в
PostgreSQL (10 баз, PgBouncer)	univex-id, ledger, p2p, exchange-integration, trades-aggregator, email, sms-gate, Exchange Engine
Redis / Valkey	univex-id (сессии, кэш, pub/sub)
Temporal.io	univex-id, ledger, p2p
S3-совместимое хранилище	univex-id (документы KYC), Exchange Engine (бэкапы ключей)
AWS SQS	email, sms-gate
AWS SNS	sms-gate