Перейти к содержанию

Univex Monorepo

Обзор

Univex — монорепозиторий, содержащий микросервисы и общие пакеты для платформы криптовалютной биржи. Версия Go: 1.23.2, корневой путь: /univex/.

Монорепозиторий объединяет 10 микросервисов, совместно обеспечивающих работу биржевой платформы: от обработки HTTP-запросов пользователей и управления аккаунтами до агрегации торговых данных, фиатных операций и KYC-верификации.


Структура репозитория

univex/
├── microservices/
│   ├── gateway/                    # HTTP-шлюз пользователей (Fiber v2, JWT)
│   │   ├── cmd/server/             # Точка входа HTTP-сервера
│   │   ├── internal/
│   │   │   ├── delivery/http/      # 65+ обработчиков маршрутов
│   │   │   │   ├── dto/            # 38 файлов Data Transfer Objects
│   │   │   │   ├── converter/      # Конвертеры account, p2p
│   │   │   │   └── responser/      # Построение HTTP-ответов
│   │   │   ├── manager/jwt/        # JWT-менеджер токенов
│   │   │   ├── storage/redis/      # Redis: сессии, кэш
│   │   │   └── locator/            # Service locator для gRPC-клиентов
│   │   └── docs/                   # Swagger (OpenAPI) спецификация
│   ├── admin-gateway/              # HTTP-шлюз администраторов (Fiber v2, Casbin RBAC)
│   │   ├── cmd/server/
│   │   ├── internal/
│   │   │   ├── delivery/http/      # 83+ обработчиков маршрутов
│   │   │   │   ├── dto/            # 50+ файлов DTO
│   │   │   │   ├── converter/
│   │   │   │   └── responser/
│   │   │   ├── casbin/             # Обёртка над Casbin enforcer (делегирует в univex-id)
│   │   │   ├── manager/jwt/
│   │   │   └── locator/
│   │   └── docs/                   # Swagger (OpenAPI) спецификация
│   ├── univex-id/                  # Основной Identity-сервис (gRPC, 95+ RPC)
│   │   ├── cmd/
│   │   │   ├── server/             # gRPC-сервер
│   │   │   ├── temporal_worker/    # Temporal workflow worker
│   │   │   ├── notification_worker/# Обработка уведомлений
│   │   │   ├── terminal_status/    # Обработка статусов KYC
│   │   │   ├── migrator/           # Миграции БД
│   │   │   └── init_roles/         # Инициализация ролей Casbin
│   │   ├── internal/
│   │   │   ├── usecase/            # 15 доменов бизнес-логики
│   │   │   │   ├── account/        # Регистрация, логин, бан, тиры (39 файлов)
│   │   │   │   ├── admin/          # CRUD админов, сессии, 2FA
│   │   │   │   ├── confirm/        # Email/Phone/Google подтверждения
│   │   │   │   ├── exchange/       # Балансы, переводы, вывод, API-ключи
│   │   │   │   ├── role/           # Casbin enforcer, RBAC-модель, политики
│   │   │   │   ├── restriction/    # Ограничения на операции
│   │   │   │   ├── google2fa/      # TOTP/Google Authenticator
│   │   │   │   ├── elliptic/       # Интеграция с Elliptic (AML)
│   │   │   │   ├── wallet_address_book/
│   │   │   │   ├── fiat_places/
│   │   │   │   ├── user_notes/
│   │   │   │   ├── user_notification/
│   │   │   │   ├── admin_notification/
│   │   │   │   ├── balance_operation/
│   │   │   │   └── hash/           # Хеширование паролей
│   │   │   ├── storage/sql/        # PostgreSQL (48 миграций)
│   │   │   ├── storage/redis/      # Redis: сессии, коды, кэш
│   │   │   ├── rpc/                # gRPC-обработчики + middleware
│   │   │   ├── temporal/           # Воркфлоу: signup, signin, ban, apikey, withdrawal, transfer
│   │   │   └── metrics/            # Prometheus-метрики
│   │   └── postgres/migrations/    # 48 SQL-миграций
│   ├── ledger/                     # Учёт и хранение балансов (gRPC, 26 RPC)
│   │   ├── cmd/
│   │   │   ├── server/
│   │   │   ├── temporal_worker/
│   │   │   └── migrator/
│   │   ├── internal/
│   │   │   ├── usecase/            # 5 доменов
│   │   │   │   ├── exchange/       # Балансы, переводы, вывод, депозиты
│   │   │   │   ├── balance_operation/ # CRUD операций с балансами
│   │   │   │   ├── frozen_assets/  # Заморозка/разморозка активов
│   │   │   │   ├── funded_codes/   # Предоплаченные коды
│   │   │   │   └── restriction/    # Ограничения операций
│   │   │   ├── hasher/             # SHA-256 хеширование для контроля целостности
│   │   │   ├── storage/sql/
│   │   │   └── temporal/           # Воркфлоу: withdrawal, transfer, fiat, freeze/unfreeze
│   │   └── postgres/migrations/    # 11 SQL-миграций
│   ├── p2p/                        # P2P-торговля (gRPC, 43 RPC)
│   │   ├── cmd/
│   │   │   ├── server/
│   │   │   ├── temporal_worker/
│   │   │   ├── migrator/
│   │   │   └── cleanup/            # Очистка устаревших данных
│   │   ├── internal/
│   │   │   ├── usecase/            # 8 доменов
│   │   │   │   ├── order/          # State machine ордеров (8 файлов)
│   │   │   │   ├── advertisement/  # CRUD объявлений
│   │   │   │   ├── message/        # Чат между участниками
│   │   │   │   ├── payment_method/ # Способы оплаты
│   │   │   │   ├── feedback/       # Отзывы и рейтинги
│   │   │   │   ├── blacklist/      # Чёрный список
│   │   │   │   ├── balance/        # P2P-балансы
│   │   │   │   └── account/        # Статистика аккаунтов
│   │   │   ├── storage/sql/
│   │   │   ├── storage/redis/      # Redis: кэш, блокировки
│   │   │   └── temporal/           # Воркфлоу: order lifecycle
│   │   └── postgres/migrations/    # 31 SQL-миграция
│   ├── exchange-integration/       # Прокси к Exchange Admin gRPC (60 RPC)
│   │   ├── cmd/{server,migrator}/
│   │   ├── internal/
│   │   │   ├── clients/admin/      # gRPC-клиент к Exchange Admin
│   │   │   ├── rpc/                # 10 обработчиков по доменам
│   │   │   ├── storage/sql/
│   │   │   └── domain/
│   │   └── postgres/migrations/    # 2 SQL-миграции
│   ├── trades-aggregator/          # Агрегатор торговых данных (gRPC streaming, 2 RPC)
│   │   ├── cmd/{server,worker,migrator}/
│   │   ├── internal/
│   │   │   ├── tradeworker/        # Фоновая агрегация через HTTP-клиент Exchange API
│   │   │   ├── rpc/
│   │   │   └── storage/sql/
│   │   └── postgres/migrations/    # 2 SQL-миграции
│   ├── email/                      # Email-сервис (gRPC + SQS)
│   │   ├── cmd/{server,queue,migrator}/
│   │   └── internal/{clients/smtp, handler, queue, storage/sql, usecase/email}/
│   ├── sms-gate/                   # SMS-шлюз (gRPC + SQS)
│   │   ├── cmd/{server,sqs,migrator}/
│   │   └── internal/{clients/sns, clients/telegram, delivery/grpc, delivery/sqs, usecase/sms}/
│   └── sumsub-integration/         # KYC-интеграция (gRPC + Fiber webhook)
│       ├── cmd/{server,webhook,migrator}/
│       └── internal/{clients/sumsub, http, rpc, usecase/applicant}/
├── proto/                          # Protobuf-определения (37 файлов, 14 пакетов)
│   ├── admin/                      # 11 proto: accounts, alerts, apikeys, assets, blockchain,
│   │                               #   hotwallets, info, operations, ping, tickers, tiers
│   ├── blockchain/                 # 7 proto: hotwallet, network, topup, transit_wallet, tx, wallet, withdrawal
│   ├── engine/                     # 5 proto: account, candle, orderbook, service, tier
│   ├── exchange_integration/       # 3 proto: основной + blockchain + tickers
│   ├── ledger/                     # 1 proto: 26 RPC
│   ├── p2p/                        # 1 proto: 43 RPC
│   ├── univex_id/                  # 3 proto: основной (95+ RPC) + admins + roles
│   ├── email/                      # 1 proto
│   ├── sms_gate/                   # 1 proto
│   ├── sms_intent/                 # 1 proto
│   ├── sumsub_integration/         # 1 proto
│   ├── trades_aggregator/          # 1 proto
│   ├── reason/                     # 1 proto: 127 кодов ошибок
│   └── passport_terminal_status_event/ # 1 proto
├── pkg/                            # Общие пакеты (17 пакетов)
│   ├── temporal/                   # Обёртки Temporal: WorkflowBase, ActivityBase,
│   │   │                           #   interceptors, helpers
│   │   ├── workflow_api/           # Executor для прямых и child-воркфлоу
│   │   ├── activity_api/           # Executor для активитей (обычных и local)
│   │   ├── default_options/        # Worker/Client interceptors для дефолтных опций
│   │   └── helpers/                # Мерж RetryPolicy, ActivityOptions
│   ├── clients/                    # HTTP/gRPC клиенты
│   │   ├── apigen/                 # Сгенерированный клиент Exchange API (OpenAPI 3.0)
│   │   ├── exchange/               # HTTP-клиент для получения сделок
│   │   └── elliptic/               # Клиент Elliptic API (AML)
│   ├── hawk/                       # Error tracking + Temporal middleware
│   ├── metrics/                    # Prometheus-обёртка для метрик
│   ├── validator/                  # Валидация входных данных
│   ├── sha256/                     # SHA-256 хеширование
│   ├── sqlxtrm/                    # Обёртка транзакций sqlx
│   ├── deps/                       # DI-хелперы (transaction factory)
│   ├── utils/                      # Утилиты: decimal, time, temporal helpers
│   ├── balogan/                    # Обёртка логгера
│   ├── jsonify/                    # JSON-утилиты
│   ├── pointer/                    # Хелпер pointer.Ref()
│   ├── slicex/                     # Операции над слайсами
│   ├── find/                       # Поиск по коллекциям
│   └── mocks/                      # Моки для тестов (Temporal client)
└── internal/                       # Общий внутренний код
    ├── config/                     # Загрузка конфигурации (Viper + cleanenv)
    ├── migrator/                   # Обёртка Goose для миграций
    ├── generated/proto/            # Сгенерированный protobuf Go-код
    └── temporal/                   # Общая Temporal-инфраструктура
        ├── activities/             # 36+ модулей активитей (shared между сервисами)
        ├── workflows/              # 10 типов воркфлоу (signup, signin, ban, transfer, withdrawal, fiat, freeze, order, apikey, manual_operation)
        ├── signals/                # Обработка сигналов подтверждения (2FA, email, admin)
        ├── domain/                 # Shared-модели для воркфлоу
        ├── common/                 # Task queues, сигналы, ошибки
        └── config/                 # Конфигурация Temporal-клиента

Сервисы монорепозитория

# Сервис Транспорт Хранилище Назначение
1 Gateway HTTP (Fiber v2) Пользовательский HTTP-шлюз, JWT, Swagger
2 Admin Gateway HTTP (Fiber v2) Административный HTTP-шлюз, Casbin RBAC, Swagger
3 UnivexID gRPC, 95+ RPC PostgreSQL (48 миграций), Redis, Temporal Основной Identity-сервис: аутентификация, аккаунты, сессии
4 Ledger gRPC, 26 RPC PostgreSQL (11 миграций), Temporal Учёт и хранение балансов: операции, переводы, фиат, funded codes
5 P2P gRPC, 43 RPC PostgreSQL (31 миграция), Redis, Temporal P2P-торговля: объявления, ордера, диспуты, чат
6 Exchange Integration gRPC, 60 RPC PostgreSQL (2 миграции) Прокси к Exchange Admin gRPC
7 Trades Aggregator gRPC стриминг, 2 RPC PostgreSQL (2 миграции) Агрегация торговых данных, тикерный стриминг
8 Email gRPC + SQS PostgreSQL (2 миграции) Отправка email через очередь
9 SMS Gate gRPC + SQS PostgreSQL SMS через SNS и Telegram
10 Sumsub Integration gRPC + Fiber webhook PostgreSQL (1 миграция) KYC-верификация через Sumsub API

Диаграмма взаимодействия сервисов

graph TD
    USER[Пользователь / Мобильное приложение]
    ADMIN_UI[Административный интерфейс]

    GW[Gateway\nHTTP Fiber v2 / JWT]
    AGW[Admin Gateway\nHTTP Fiber v2 / Casbin RBAC]

    UID[univex-id\ngRPC 95+ RPC]
    LED[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 + SQS]
    SMS[sms-gate\ngRPC + SQS + SNS]
    SUMSUB[sumsub-integration\ngRPC + webhook]

    ENG[Exchange Admin gRPC\nвнешний движок]
    EXHTTP[Exchange HTTP API]
    TEMPORAL[Temporal.io]
    SQS[AWS SQS]
    SNS[AWS SNS / Telegram]
    SUMSUB_API[Sumsub API]

    USER -->|HTTP| GW
    ADMIN_UI -->|HTTP| AGW

    GW -->|gRPC| UID
    GW -->|gRPC| LED
    GW -->|gRPC| P2P
    GW -->|gRPC| TA
    GW -->|gRPC| EI

    AGW -->|gRPC| UID
    AGW -->|gRPC| LED
    AGW -->|gRPC| P2P
    AGW -->|gRPC| EI

    UID -->|gRPC| EMAIL
    UID -->|gRPC| SMS
    UID -->|gRPC| SUMSUB
    UID -->|gRPC| EI

    EI -->|Admin gRPC| ENG

    TA -->|HTTP| EXHTTP
    TEMPORAL -->|Workflow| TA
    TEMPORAL -->|Workflow| LED
    TEMPORAL -->|Workflow| P2P
    TEMPORAL -->|Workflow| UID

    EMAIL -->|queue| SQS
    SMS -->|queue| SQS
    SMS -->|push| SNS
    SUMSUB -->|webhook| SUMSUB_API

Общая инфраструктура

proto/ — Protobuf-определения

37 .proto-файлов, 14 пакетов. Каждый микросервис описывает свой gRPC-контракт в отдельном файле. Сгенерированный код хранится в internal/generated/.

Основные пакеты:

Пакет Описание
gateway Маршруты и типы HTTP-шлюза
univex_id Identity-сервис (95+ RPC)
ledger Леджер (26 RPC)
p2p P2P-торговля (43 RPC)
exchange_integration Интеграция с биржей (60 RPC)
trades_aggregator Агрегация торгов (2 RPC)
email_service Email
sms_gate SMS
sumsub_integration KYC

pkg/ — Общие пакеты (15 штук)

Пакет Назначение
balogan Структурированное логирование
clients HTTP/gRPC-клиенты (exchange, apigen)
deps Инъекция зависимостей
find Вспомогательные функции поиска
hawk Утилиты для обработки ошибок
jsonify JSON-утилиты
metrics Метрики (Prometheus)
mocks Тест-моки
pointer Работа с указателями на примитивы
sha256 SHA-256 хэширование
slicex Обобщённые операции со срезами
sqlxtrm Управление SQL-транзакциями
temporal Обёртки Temporal workflow/activity SDK
utils Общие утилиты
validator Валидация входных данных

internal/ — Внутренний общий код

Директория Назначение
internal/config/ Единый способ чтения конфигурации из переменных окружения
internal/migrator/ Запуск SQL-миграций при старте сервиса
internal/generated/ Автосгенерированный protobuf Go-код (не редактировать вручную)
internal/temporal/ Базовые настройки Temporal worker для сервисов

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

Компонент Технология
Язык Go 1.24.4
HTTP-сервер Fiber v2
Межсервисное взаимодействие gRPC / Protocol Buffers
Авторизация (пользователи) JWT
Авторизация (администраторы) JWT + Casbin RBAC
Фоновые задачи Temporal.io
База данных PostgreSQL (sqlx)
Кэш / очереди Redis, AWS SQS, AWS SNS
Миграции Внутренний migrator
Логирование balogan (структурированное)
Метрики Prometheus (pkg/metrics)
KYC Sumsub API
SMS AWS SNS + Telegram
Email SMTP

Дополнительная документация