System Overview Architecture (Integration-Only)¶

Архитектура системы Saga после принятия Integration-Only решения. Saga больше не управляет криптовалютными операциями, wallet'ами или HD Wallet. Все операции делегированы специализированным сервисам.

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

High-Level Architecture (Integration-Only)¶

graph TB
    subgraph "Users"
        U1[👤 Regular User\nEmail-first]
        A1[👨‍💼 Admin\nOperator]
    end

    subgraph "Frontend Layer"
        UA[📱 User App\nNext.js]
        AA[🛠️ Admin App\nNext.js]
        SC[🔄 Shared Config\nTypeScript]
    end

    subgraph "Backend Layer"
        API[🌐 REST API\nGolang]
        AUTH[🔐 Auth Service\nEmail + JWT]
        C2B[💳 Crypto2B Service\nDeposits Only]
        INV[💼 Investment Service]
        BAL[💰 Balance Service]
        NOT[📧 Notification Service]
    end

    subgraph "Data Layer"
        PG[(🗄️ PostgreSQL\nTracking + Analytics)]
        CFG[⚙️ Unified Config\nYAML + ENV]
    end

    subgraph "External Custody (Third-Party)"
        C2B_EXT["💳 Crypto2B\nDeposits + Withdrawals"]
        FORD["💼 Fordefi\nAsset Management"]
        DEFI["🏦 DeFi Protocols\nYield Generation"]
    end

    %% User interactions
    U1 --> UA
    A1 --> AA

    %% Frontend to Backend
    UA --> API
    AA --> API
    SC --> UA
    SC --> AA

    %% API to Services
    API --> AUTH
    API --> C2B
    API --> INV
    API --> BAL
    API --> NOT

    %% Services to Data
    AUTH --> PG
    C2B --> PG
    INV --> PG
    BAL --> PG
    NOT --> PG

    %% Configuration
    CFG --> API
    CFG --> AUTH
    CFG --> C2B
    CFG --> INV
    CFG --> BAL

    %% External integrations (Third-Party)
    AUTH --> UA
    AUTH --> AA

    C2B --> C2B_EXT
    C2B_EXT -.->|webhooks| C2B

    FORD --> DEFI
    A1 -.->|manual decisions| FORD

    %% Styling
    classDef frontend fill:#4A90E2,stroke:#2E5C8A,color:#fff
    classDef backend fill:#7ED321,stroke:#5BA116,color:#fff
    classDef data fill:#F5A623,stroke:#D48806,color:#fff
    classDef external fill:#D0021B,stroke:#A8021B,color:#fff
    classDef users fill:#9013FE,stroke:#6200EA,color:#fff

    class UA,AA,SC frontend
    class API,AUTH,C2B,INV,BAL,NOT backend
    class PG,CFG data
    class C2B_EXT,FORD,DEFI external
    class U1,A1 users

Component Breakdown (Integration-Only)¶

Frontend Layer¶

User App: Next.js приложение для пользователей (Email-based)
Admin App: Next.js приложение для администраторов
Shared Config: Общие TypeScript типы и конфигурация

Backend Layer¶

REST API: Единая точка входа для всех HTTP запросов
Auth Service: Email-first аутентификация (Supabase + JWT) - НЕ Web3
Crypto2B Service: Интеграция с Crypto2B для депозитов и выводов - НИКАКИХ WALLET ОПЕРАЦИЙ
Investment Service: Управление инвестиционными продуктами (просто tracking)
Balance Service: Управление балансами пользователей (расчет по transactions)
Notification Service: Email уведомления

Data Layer¶

PostgreSQL: База данных для tracking, analytics, transactions
Unified Config: Централизованная конфигурация системы (ADMIN_EMAILS, API keys)

External Services (Управляются операторами)¶

Crypto2B: Управление всеми депозитами и выводами криптовалют
Fordefi: Профессиональное управление активами и custody
DeFi Protocols: Размещение средств для генерации yield

Key Design Principles (Integration-Only)¶

Integration-Only: ❌ Никаких криптовалютных операций на платформе
Email-First Auth: ✅ Только email/password + Google OAuth
No HD Wallet: ❌ Никаких приватных ключей или адресов
External Custody: ✅ Все активы в Fordefi/Crypto2B
Tracking Only: ✅ Saga только отслеживает и отчитывается
Third-Party Operations: ✅ Операторы принимают решения, а не система

Security Boundaries¶

graph LR
    subgraph "Public Zone"
        PZ[🌐 Internet]
    end

    subgraph "Saga DMZ"
        FE[🔒 Frontend Apps]
        API[🔒 REST API]
    end

    subgraph "Saga Private"  
        SRV[🔐 Backend Services]
        DB[🔐 Database]
        CFG[🔐 Config]
    end

    subgraph "External Custody"
        C2B_INT["🔐 Crypto2B\nMulti-sig"]
        FORD_INT["🔐 Fordefi\nEnterprise Grade"]
    end

    PZ --> FE
    FE --> API
    API --> SRV
    SRV --> DB
    SRV --> CFG
    SRV --> C2B_INT
    SRV --> FORD_INT

    classDef public fill:#ff6b6b
    classDef saga_dmz fill:#ffd93d  
    classDef saga_private fill:#6bcf7f
    classDef custody fill:#4A90E2

    class PZ public
    class FE,API saga_dmz
    class SRV,DB,CFG saga_private
    class C2B_INT,FORD_INT custody

Data Flow Patterns (Integration-Only)¶

Authentication: User → Frontend (Supabase) → API → Auth Service → JWT (Email-based)
Deposits: External address from Crypto2B → User sends crypto → Crypto2B webhook → API → Database
Withdrawals: User request → API → Admin approval → Fordefi → Blockchain execution
Investments: User → API → Investment Service → Database (no crypto operations)
Balance Tracking: All transactions → Balance Service → Calculated balance (not blockchain sourced)

Technology Stack¶

Frontend: Next.js, TypeScript, TailwindCSS, wagmi (read-only)
Backend: Go, Gorilla Mux, PostgreSQL
Authentication: Supabase Auth (Email + Google OAuth), JWT
External Services: Crypto2B API, Fordefi API, Webhooks
Testing: Playwright (E2E), Go testing, No mocks
DevOps: Docker, Makefile, Git hooks

Architecture Decisions¶

See related ADR for detailed decisions: - ADR-0001: Web3 Wallet Authentication (DEPRECATED - replaced by email-first) - ADR-0004: Integration-Only Architecture (CURRENT - 2025-11-13)

⚠️ ВАЖНО¶

Эта диаграмма показывает текущую архитектуру Integration-Only после принятия ADR-0004.

Что УДАЛЕНО: - ❌ HD Wallet management - ❌ Private key management - ❌ Blockchain monitoring - ❌ Web3 wallet authentication - ❌ Smart contracts for custody

Что ДОБАВЛЕНО: - ✅ Email-first authentication - ✅ Crypto2B integration - ✅ Fordefi partnership - ✅ Webhook-based operations - ✅ Third-party custody model