ADR-0004: Integration-Only Architecture¶

Статус¶

Accepted (Superseded previous HD Wallet approach - 2025-11-14)

Контекст¶

Проект Saga для персональных пенсионных криптофондов требует безопасного, масштабируемого и compliance-ready управления активами. Первоначально рассматривался собственный HD Wallet подход, но анализ показал критические ограничения для enterprise-решений.

Требования: - Полная безопасность и compliance для пенсионных средств - Минимальный time-to-market для MVP - Enterprise-grade надежность - Разделение ответственности (separation of concerns) - Масштабируемость для тысяч пользователей

Ограничения первоначального HD Wallet подхода: - Высокие требования к security для управления приватными ключами - Необходимость compliance сертификации для собственного custody - Сложность мониторинга множественных blockchain сетей - Риски при управлении критически важными пенсионными активами

Решение¶

Integration-Only архитектура - полный отказ от собственного управления криптовалютными активами в пользу специализированных enterprise-провайдеров.

Архитектура компонентов:¶

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Saga Platform │    │   Crypto2B API  │    │    Fordefi      │
│                 │    │                 │    │                 │
│ • User Auth     │◄──►│ • Deposit APIs  │◄──►│ • Custody       │
│ • Investment    │    │ • Webhook       │    │ • Multi-sig     │
│ • Analytics     │    │ • Address Gen   │    │ • Enterprise    │
│ • Reporting     │    │ • Balance Query │    │ • Compliance    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Принципы Integration-Only:¶

Никаких приватных ключей на платформе
Fordefi обеспечивает enterprise custody
Multi-signature security
Institutional-grade compliance
API-driven операции
Crypto2B для депозитов и balance queries
Fordefi для withdrawals и DeFi операций
Webhook-based уведомления
Разделение ответственности:
Saga: UX, инвестиционная логика, аналитика
Crypto2B: депозитные операции, адреса
Fordefi: custody, security, compliance

Ключевые интеграции:¶

Crypto2B Integration: - Автоматическая генерация депозитных адресов - Real-time webhook уведомления о депозитах - Balance queries через REST API - Support множественных сетей (ETH, BTC, др.)

Fordefi Integration: - Enterprise custody решение - Multi-sig wallet management - Compliance-ready withdrawal процессы - DeFi операции для yield generation

Альтернативы¶

HD Wallet Architecture (собственная разработка)¶

Отклонена (2025-11-14) - неоправданные риски для пенсионных средств: - Требует extensive security audit и compliance сертификации - Высокие costs разработки и поддержки security инфраструктуры - Single point of failure в управлении ключами - Медленный time-to-market

Hybrid подход (частичное собственное управление)¶

Отклонена - усложняет архитектуру без преимуществ: - Смешанная ответственность создает gaps в security - Сложность debugging и troubleshooting - Regulatory compliance становится неопределенной

Single custody provider¶

Рассматривалось - но выбрана комбинация Crypto2B + Fordefi: - Crypto2B специализируется на deposit flows - Fordefi specialized на enterprise custody и withdrawals - Diversification security рисков между провайдерами

Последствия¶

Положительные¶

Reduced risk: Enterprise-grade security без собственных ключей
Faster MVP: Готовые API вместо собственной разработки
Compliance: Провайдеры уже имеют необходимые сертификации
Scalability: Proven enterprise инфраструктура
Cost efficiency: Капекс в операкс, предсказуемые затраты
Focus: Команда фокусируется на UX и business logic

Отрицательные¶

Vendor dependency: Зависимость от внешних провайдеров
Integration complexity: Необходимость координации между API
Fees: Комиссии провайдеров за services
Limited control: Меньший контроль над низкоуровневыми операциями

Нейтральные¶

API learning curve: Команда изучает сторонние API
Monitoring setup: Настройка мониторинга external dependencies

Связанные решения¶

Связано с: ADR-0001 (Email-First Authentication) - аутентификация отделена от custody
Связано с: System Architecture Overview - принципы Integration-Only
Заменяет: ADR-0004-DEPRECATED (HD Wallet Architecture)

Примечания¶

Migration path: Existing HD Wallet код archived в /deprecated/
Security model: Trust model основан на enterprise провайдерах
Compliance: Провайдеры предоставляют compliance reporting
Future extensibility: Архитектура позволяет добавление новых провайдеров
Disaster recovery: Провайдеры обеспечивают backup и recovery процедуры

Версионирование¶

v1: HD Wallet Architecture (DEPRECATED 2025-11-14)
v2: Integration-Only Architecture (CURRENT from 2025-11-14)