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

Critical Paths Documentation - Документация критических путей (Integration-Only)

АРХИТЕКТУРНОЕ РЕШЕНИЕ: ADR-0004 - Integration-Only Architecture (2025-11-13)

Обзор

Эта папка содержит детальную документацию критических путей системы Saga - финансовой платформы с Integration-Only архитектурой. Каждый документ описывает полный поток от frontend запроса до external service integration с архитектурными принципами, схемами базы данных и security checklist'ами.

Документы

Authentication Flow

Критический путь аутентификации (Integration-Only) - Email-first authentication через Supabase (Google OAuth + email/password) - Никаких Web3 wallet signature verification - ЗАМЕНЕНО на Email - Config-based admin management (НЕ в БД) - JWT токены с Supabase verification

Ключевые компоненты:

  • AdminAuthRouter + UserAuthRouter → AdminAuthService → AuthMiddleware
  • SupabaseAuthContext (React) → AuthService (API)
  • Email-based идентификация (PRIMARY IDENTIFIER)

Deposits Flow

Критический путь депозитов и пополнений (Integration-Only) - Crypto2B API интеграция для всех депозитных операций - Webhook-based обработка депозитов (НЕ blockchain мониторинг) - Никаких HD Wallet или BIP44 - все адреса от Crypto2B - Immutable transaction records в PostgreSQL - Поддерживаемые сети: TRC20 (USDT), ERC20 (USDC), BSC, Polygon

Ключевые компоненты:

  • Crypto2BService → WebhookHandler → Transaction recording
  • Real-time депозит уведомления
  • Balance updates через transactions table

Withdrawals Flow

Критический путь выводов средств (Integration-Only) - Fordefi API для управления выводами и custody - Admin approval + compliance checks (Fordefi multi-sig) - Two-phase commit: request → execution - Никаких HD Wallet или blockchain операций Saga - всё через Fordefi

Ключевые компоненты:

  • WithdrawalService → FordefiService → External execution
  • Admin approval dashboard (Fordefi web interface)
  • Multi-level security: Balance validation → Admin → Fordefi

Архитектурные принципы (Integration-Only)

Все критические пути следуют единым принципам Integration-Only архитектуры:

Security First (Integration-Only)

  • ❌ ЗАПРЕТ: Email/password authentication (ИСПОЛЬЗУЕТСЯ SUPABASE)
  • ❌ ЗАПРЕТ: Web3 wallet authentication (ИСПОЛЬЗУЕТСЯ EMAIL)
  • ❌ ЗАПРЕТ: Приватные ключи в системе Saga
  • ❌ ЗАПРЕТ: Blockchain мониторинг своими силами (Crypto2B делает)
  • ❌ ЗАПРЕТ: HD Wallet или BIP44 derivation
  • ✅ ОБЯЗАТЕЛЬНО: Supabase email verification
  • ✅ ОБЯЗАТЕЛЬНО: External Crypto2B/Fordefi для криптовалютных операций
  • ✅ ОБЯЗАТЕЛЬНО: Immutable transaction records

Separation of Concerns (Integration-Only)

  • Saga Platform: UI, business logic, tracking, reporting
  • Crypto2B: Управление депозитами и выводами
  • Fordefi: Управление активами, custody, yield optimization
  • Операторы: Стратегические решения (ручное управление)

Clean Architecture

  • Handler → HTTP endpoints и validation
  • Service → Бизнес-логика и orchestration
  • Repository → Данные и persistence
  • Models → Shared domain объекты

Database Design

  • transactions table как single source of truth
  • type field для deposit/withdrawal/investment разделения
  • Audit trail для всех финансовых операций
  • Consistency checks между calculated и recorded балансами

Real-time Experience

  • Webhook обновления из Crypto2B и Fordefi
  • Progressive status (requested → processing → completed)
  • Error recovery с automatic rollback
  • User notifications на каждом этапе

Взаимосвязи между путями

Authentication → Deposits

  • Authenticated user_id (из Email JWT) используется для tracking депозитов
  • Email адрес = PRIMARY IDENTIFIER пользователя
  • Никаких HD Wallet derivation - Crypto2B генерирует адреса

Authentication → Withdrawals

  • Email verification используется для withdrawal requests
  • Admin approval проверяет admin status из config.yaml
  • User balance validation требует authenticated context

Deposits → Withdrawals

  • Deposits увеличивают balance через transactions table
  • Withdrawals проверяют достаточность средств из того же источника
  • transactions table содержит полную историю inflow/outflow

Testing Strategy

Unit Tests

Каждый критический путь имеет покрытие: - Email validation logic - Crypto2B webhook parsing - Fordefi integration tests - Database transaction integrity - Error handling scenarios

Integration Tests

End-to-end тестирование потоков: - Crypto2B webhook flow (реальные webhooks) - Fordefi withdrawal flow - Multi-step workflows (request → approval → execution)

Security Tests

  • JWT validation и expiration
  • Email verification bypass attempts
  • Balance manipulation attempts
  • Race condition scenarios
  • Admin privilege escalation

Мониторинг и метрики

Критические метрики всех путей:

  • Throughput: operations per hour/day
  • Latency: time from request to completion
  • Success Rate: percentage of successful operations
  • Webhook reliability: Crypto2B/Fordefi webhook delivery rate
  • Error tracking: failed authentications, API errors

Алерты:

  • Large transactions requiring attention
  • High failure rates indicating system issues
  • Balance inconsistencies requiring investigation
  • Webhook delivery failures
  • External API timeout/errors

Troubleshooting Guide

Authentication Issues

  • Email verification failures → проверка Supabase Auth
  • Admin access denied → config.yaml ADMIN_EMAILS validation
  • JWT expiration → token refresh flow

Deposits Issues

  • Missing deposits → Crypto2B webhook status
  • Wrong amounts → Crypto2B API response parsing
  • Address validation errors → Crypto2B network support

Withdrawals Issues

  • Approval delays → Fordefi dashboard check
  • Execution failures → Fordefi compliance/network status
  • Balance inconsistencies → audit trail analysis

Deployment Considerations

Configuration

Все пути используют unified configuration: - config.yaml для production settings - Environment variables для secrets (CRYPTO2B_API_KEY, FORDEFI_API_KEY) - Test configuration isolation

Security

  • API key management для external services
  • Rate limiting на всех public endpoints
  • CORS protection для cross-origin security
  • Audit logging всех security-relevant events
  • Webhook signature verification для Crypto2B/Fordefi

Scalability

  • Database indexing для performance
  • Connection pooling для высокой нагрузки
  • Caching для frequently accessed data
  • Horizontal scaling готовность
  • Webhook queue для high-volume transaction processing

Связанная документация

Systems Validation

  • Reality Check Report - Полное системное исследование и проверка документации критических путей

Архитектурные решения (ADR)

Диаграммы системы

  • System Overview - Общий обзор архитектуры Integration-Only
  • Auth Flow - Диаграмма аутентификации
  • Deposit Flow - Диаграмма депозитов (Crypto2B)
  • Withdrawal Flow - Диаграмма выводов (Fordefi)

Модули системы

Руководства

⚠️ ВАЖНО: Integration-Only Архитектура

УДАЛЕНО из системы: - ❌ HD Wallet management - ❌ Private key storage - ❌ BIP44 derivation - ❌ Blockchain monitoring - ❌ Web3 wallet authentication - ❌ Smart contracts for custody - ❌ user_wallet_addresses таблица

ДОБАВЛЕНО в систему: - ✅ Email-first authentication (Supabase) - ✅ Crypto2B API integration - ✅ Fordefi partnership - ✅ Webhook-based notifications - ✅ External custody model - ✅ Operator-driven decisions

🤝 Contributing

При изменениях в критических путях:

  1. Обновить соответствующий документ в этой папке
  2. Проверить архитектурные принципы - соответствие Integration-Only
  3. Запустить security checklist из каждого документа
  4. Обновить тесты покрывающие изменения
  5. Провести code review с фокусом на безопасность

Принцип: Критические пути должны быть максимально понятными и прослеживаемыми для обеспечения безопасности финансовой системы.

Архитектурное решение: Все решения принимаются в контексте Integration-Only архитектуры (ADR-0004).