Архитектура 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 тесты — только для критических пользовательских путей
- Никаких моков для внутренних компонентов
🏛️ Слоистая архитектура¶
flowchart TB
subgraph FRONTEND["Frontend Layer"]
UA["User App<br/>(Next.js :3000)"]
AA["Admin App<br/>(Next.js :3001)"]
end
subgraph API["API Layer"]
CR["CompositeRouter"]
UR["UserRouter"]
AR["AdminRouter"]
AUR["AuthRouter"]
end
subgraph BUSINESS["Business Layer"]
AS["AuthService"]
IS["InvestmentService"]
NS["NotificationService"]
SS["StorageService"]
end
subgraph DATA["Data Layer"]
URep["UserRepository"]
IRep["InvestmentRepository"]
TRep["TransactionRepository"]
end
DB[("PostgreSQL + JSONB")]
FRONTEND -->|REST API| API
API -->|Service calls| BUSINESS
BUSINESS -->|Repository calls| DATA
DATA -->|SQL queries| DB
style FRONTEND fill:#e3f2fd
style API fill:#fff3e0
style BUSINESS fill:#e8f5e9
style DATA fill:#fce4ecСтруктура проекта (АКТУАЛЬНАЯ)¶
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 # Аутентификация
│ │ └── services/ # Бизнес-сервисы
│ ├── storage/ # Слой данных
│ │ ├── repository/ # Только SQL запросы
│ │ ├── interfaces/ # Интерфейсы репозиториев
│ │ └── migrations/ # Миграции БД
│ ├── auth/ # Модуль аутентификации
│ │ ├── service/ # Бизнес-логика аутентификации
│ │ └── repository/ # SQL запросы для auth
│ ├── crypto2b/ # Интеграция Crypto2B (deposits)
│ │ └── service.go # Crypto2B API клиент
│ ├── fordefi/ # Интеграция Fordefi (withdrawals)
│ │ └── client.go # Fordefi API клиент
│ └── 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 провайдеров
Пирамида тестирования¶
%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px'}}}%%
graph TB
subgraph PYRAMID["Testing Pyramid"]
E2E["🔝 E2E (Few)<br/>Critical paths only"]
INT["⭐ Integration (Many)<br/>ОСНОВНОЙ СЛОЙ<br/>Реальные HTTP + БД тесты"]
UNIT["📦 Unit (Some)<br/>Чистые функции и утилиты"]
end
E2E --> INT
INT --> UNIT
style INT fill:#90EE90,stroke:#228B22,stroke-width:3px
style E2E fill:#FFB6C1
style UNIT fill:#87CEEBТипы тестов¶
- Smoke (8 сек): Критичная проверка перед коммитом
- Core (1-2 мин): Важные изменения в коде
- Integration: Основной слой - реальный сервер + тестовая БД
- E2E: Только критические пользовательские пути
- Advanced: Mutation, Property-based, Contract тесты
Принципы качества¶
Краткость¶
- Минимизация вывода токенов
- Избегание ненужных пояснений
- Фокус на конкретных задачах
Точность¶
- Проверка реального состояния системы
- Поиск первопричин проблем
- Доверие фактам, а не сообщениям об ошибках
Эффективность¶
- Использование абсолютных путей
- Параллельное выполнение команд где возможно
- Пакетирование tool calls в одном сообщении
Цель архитектуры: Простая, понятная, масштабируемая система без технического долга.
Детальные критические пути¶
Для понимания работы системы от запроса до ответа см. документацию критических путей:
🎯 Основная архитектура¶
- 🏗️ Системная архитектура Integration-Only MVP - ГЛАВНЫЙ ДОКУМЕНТ: Полная архитектура с диаграммами, workflow операторов и техническими деталями
Критические пути¶
- Authentication Flow - Email-first аутентификация через Supabase Auth
- Deposits Flow - Crypto2B API интеграция с webhook уведомлениями
- Withdrawals Flow - Fordefi enterprise custody с админ approval
Каждый документ содержит sequence диаграммы, схемы БД, security checklist'ы и troubleshooting guide.