Архитектура Saga - Единый источник истины¶
Обзор проекта¶
Saga — современная инвестиционная DeFi-платформа с унифицированной архитектурой, построенная на принципах Clean Architecture, автоматической генерации типов и реального интеграционного тестирования.
Золотые правила архитектуры¶
1. ЕДИНЫЙ API (REST-only)¶
- Протокол: Только REST API, JSON-RPC полностью удалён
- Endpoints: Консолидированы в
backend/shared/routing/ - Стандарты: HTTP методы (GET, POST, PUT, DELETE), JSON запросы/ответы
- Никаких RPC или GraphQL
2. ЕДИНЫЕ МОДЕЛИ ДАННЫХ¶
- Источник истины:
backend/shared/models/— единственное место для Go структур - Автогенерация: TypeScript типы генерируются из Go структур через
cmd/typegen - Синхронизация: Команда
make generate-typesпосле изменения Go моделей - Никаких дублирующих определений типов
3. ЧИСТАЯ АРХИТЕКТУРА¶
Запросы обрабатываются строго по цепочке:
- Handlers: Только парсинг запросов и вызов сервисов - Services: Только бизнес-логика и валидация- Repositories: Только SQL запросы к БД - Никакой бизнес-логики в хендлерах, никакого SQL в сервисах
4. РЕАЛЬНЫЕ ТЕСТЫ¶
- Интеграционные тесты как основной слой — используют реальный HTTP сервер и тестовую PostgreSQL БД
- Unit-тесты — только для утилит и чистых функций
- E2E тесты — только для критических пользовательских путей
- Никаких моков для внутренних компонентов
🏛️ Слоистая архитектура¶
┌─────────────────────────────────────┐
│ Frontend Layer │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ User App │ │ Admin App │ │
│ │ (Next.js) │ │ (Next.js) │ │
│ │ :3000 │ │ :3001 │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────┘
│ REST API calls │
┌─────────────────────────────────────┐
│ API Layer │
│ ┌─────────────────────────────┐ │
│ │ Consolidated Routers │ │
│ │ • CompositeRouter (main) │ │
│ │ • UserRouter │ │
│ │ • AdminRouter │ │
│ │ • AuthRouter │ │
│ │ • BlockchainRouter │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
│ Service calls │
┌─────────────────────────────────────┐
│ Business Layer │
│ ┌─────────────────────────────┐ │
│ │ Services │ │
│ │ • AuthService │ │
│ │ • InvestmentService │ │
│ │ • BlockchainService │ │
│ │ • NotificationService │ │
│ │ • StorageService │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
│ Repository calls │
┌─────────────────────────────────────┐
│ Data Layer │
│ ┌─────────────────────────────┐ │
│ │ Repositories │ │
│ │ • UserRepository │ │
│ │ • InvestmentRepository │ │
│ │ • TransactionRepository │ │
│ │ • WalletRepository │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
│ SQL queries │
┌─────────────────────────────────────┐
│ Database Layer │
│ PostgreSQL + JSONB │
└─────────────────────────────────────┘
Структура проекта (АКТУАЛЬНАЯ)¶
Saga/
├── backend/ # Монолитный Go сервер
│ ├── cmd/ # Исполняемые команды
│ │ ├── typegen/ # Генератор TypeScript типов
│ │ ├── migrate/ # Управление миграциями БД
│ │ └── saga/ # Основной сервер
│ │ └── main.go # Точка входа сервера
│ ├── main # Исполняемый файл backend
│ ├── config.yaml # Конфигурация приложения
│ ├── shared/ # Унифицированные компоненты
│ │ ├── models/ # ЕДИНЫЕ модели данных (источник истины)
│ │ ├── routing/ # Консолидированные роутеры
│ │ │ ├── composite_router.go # Главный роутер
│ │ │ ├── user_router.go # Пользовательские операции
│ │ │ ├── admin_router.go # Административные операции
│ │ │ ├── auth_router.go # Аутентификация
│ │ │ └── blockchain_router.go # Блокчейн операции
│ │ └── services/ # Бизнес-сервисы
│ ├── storage/ # Слой данных
│ │ ├── repository/ # Только SQL запросы
│ │ ├── interfaces/ # Интерфейсы репозиториев
│ │ └── migrations/ # Миграции БД
│ ├── auth/ # Модуль аутентификации
│ │ ├── service/ # Бизнес-логика аутентификации
│ │ └── repository/ # SQL запросы для auth
│ ├── blockchain/ # Модуль блокчейн интеграции
│ │ ├── service/ # Блокчейн бизнес-логика
│ │ └── repository/ # Блокчейн SQL запросы
│ └── notification/ # Модуль уведомлений
│ ├── service/ # Email и push уведомления
│ └── repository/ # Уведомления в БД
│
├── frontend/ # Frontend приложения
│ ├── shared/ # Общие компоненты
│ │ ├── types/ # Автогенерированные TypeScript типы
│ │ │ ├── generated-types.ts # Сгенерированные из Go
│ │ │ └── unified-types.ts # Унифицированные экспорты
│ │ ├── components/ # Переиспользуемые компоненты
│ │ └── lib/ # Общие утилиты
│ ├── user-app/ # Пользовательское приложение
│ │ ├── src/app/ # Next.js App Router
│ │ └── src/components/ # Компоненты пользователя
│ └── admin-app/ # Административная панель
│ ├── src/app/ # Next.js App Router
│ └── src/components/ # Компоненты админки
│
├── scripts/ # Скрипты автоматизации
│ ├── run-dev-monolith.sh # Единый скрипт запуска dev среды
│ └── update-types.sh # Генерация TypeScript типов
│
└── docs/ # Централизованная документация
├── architecture/ # Архитектурные решения
├── guides/ # Руководства разработчика
├── modules/ # Документация модулей
└── archive/ # Архив отчётов
Процессы разработки¶
Основные команды¶
make build-container # Запуск единого контейнера (Cloud Native)
make test-smoke # Быстрые критичные тесты (~8 сек)
make test-core # Основные тесты (~1-2 мин)
make test-all # Полное тестирование (~10+ мин)
make generate-types # Генерация TypeScript типов из Go
Workflow добавления функций¶
- Модель: Создать Go структуру в
shared/models/ - Repository: Добавить SQL в
storage/repository/ - Service: Реализовать бизнес-логику
- Handler: Добавить HTTP endpoint в роутер
- Типы:
make generate-types - Тест: Создать интеграционный тест
Безопасность Integration-Only¶
Enterprise Security Architecture¶
- Никаких приватных ключей на Saga платформе
- Fordefi Enterprise Custody - multi-signature security для withdrawals
- Crypto2B API - enterprise депозитные операции с webhook verification
- Supabase Auth - SOC 2 Type II compliance для аутентификации
API Security Best Practices¶
- ВСЕГДА проверяй exit code команд:
echo "Exit code: $?" - НИКОГДА не считай API responses successful по умолчанию
- Неизвестный статус = failed, НЕ successful
- Валидируй webhook signatures от external провайдеров
Пирамида тестирования¶
E2E (Few)
Critical paths only
Integration (Many) ← ОСНОВНОЙ СЛОЙ
Реальные HTTP + БД тесты
Unit (Some utilities only)
Чистые функции и утилиты
Типы тестов¶
- Smoke (8 сек): Критичная проверка перед коммитом
- Core (1-2 мин): Важные изменения в коде
- Integration: Основной слой - реальный сервер + тестовая БД
- E2E: Только критические пользовательские пути
- Advanced: Mutation, Property-based, Contract тесты
Принципы качества¶
Краткость¶
- Минимизация вывода токенов
- Избегание ненужных пояснений
- Фокус на конкретных задачах
Точность¶
- Проверка реального состояния системы
- Поиск первопричин проблем
- Доверие фактам, а не сообщениям об ошибках
Эффективность¶
- Использование абсолютных путей
- Параллельное выполнение команд где возможно
- Пакетирование tool calls в одном сообщении
Цель архитектуры: Простая, понятная, масштабируемая система без технического долга.
Детальные критические пути¶
Для понимания работы системы от запроса до ответа см. документацию критических путей:
🎯 Основная архитектура¶
- 🏗️ Системная архитектура Integration-Only MVP - ГЛАВНЫЙ ДОКУМЕНТ: Полная архитектура с диаграммами, workflow операторов и техническими деталями
Критические пути (Integration-Only)¶
- Authentication Flow - Email-first аутентификация через Supabase Auth
- Deposits Flow - Crypto2B API интеграция с webhook уведомлениями
- Withdrawals Flow - Fordefi enterprise custody с админ approval
Каждый документ содержит sequence диаграммы, схемы БД, security checklist'ы и troubleshooting guide.