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

👨‍💻 Developer Documentation

Документация для backend и frontend разработчиков, интеграторов и contributors проекта Saga.

Quick Start

Первые шаги

  1. Onboarding Guide - быстрый старт для новых разработчиков
  2. Architecture Overview - понимание системы
  3. Development Setup - настройка локального окружения

Основные команды

make restart              # Запуск системы
make test                 # Foundation тесты
make analyze              # Анализ кода

Основные разделы

API Documentation

📖 API Reference Полная документация всех 102 REST API endpoints

🔐 Authentication Web3 wallet authentication + JWT tokens

❌ Error Handling Стандарты обработки ошибок, error codes

📂 Examples (Coming soon: примеры request/response для всех endpoints)

Architecture

🏗️ Integration-Only MVP System Architecture ⭐ ГЛАВНЫЙ ДОКУМЕНТ: Полная архитектура системы с диаграммами, workflow операторов и техническими деталями

📐 Architecture Overview High-level обзор системной архитектуры

📋 ADRs (Architecture Decision Records) Документированные архитектурные решения

📊 System Diagrams Визуализация компонентов и data flows

🔥 Critical Paths Authentication, Deposits, Withdrawals, Investment flows

Developer Guides

🚀 Onboarding Быстрый старт для новых contributors

⚙️ Development Setup Настройка локального окружения

🧪 Testing Guide Unit, integration, E2E тестирование

🚀 Deployment Blue-Green deployment на VPS, CI/CD

🗄️ Database Migrations Работа с PostgreSQL миграциями

📦 Configuration UnifiedConfig система, environment variables

🔧 Troubleshooting Решение частых проблем

🧩 Modules

Backend модули:

Frontend модули:

  • User App - Пользовательское приложение
  • Admin App - Административная панель

🛠️ Tools

📝 CLI Reference Makefile команды и утилиты

Technology Stack

Backend

  • Language: Go 1.24.x
  • Router: Gorilla Mux, Clean Architecture
  • Database: PostgreSQL 14+
  • Auth: Web3 (MetaMask), JWT
  • Testing: Go test, integration tests

Frontend

  • Framework: Next.js 15.x (App Router)
  • Language: TypeScript
  • UI: React, TailwindCSS
  • Auth: Supabase Auth (Email-first)
  • Testing: Playwright (E2E), Jest (unit)

Integration APIs

  • Crypto2B: Deposit operations and webhooks
  • Fordefi: Enterprise custody for withdrawals
  • Supabase: Email-first authentication

Infrastructure

  • Containers: Docker (единый контейнер)
  • Deployment: Blue-Green на VPS
  • CI/CD: GitHub Actions
  • Monitoring: Canonical logging (slog)

📖 Code Standards

Backend (Go)

  • ✅ Clean Architecture (Handler → Service → Repository)
  • ✅ SafeDecimal для финансовых операций
  • ✅ UnifiedConfig для всех настроек
  • ✅ Canonical logging (slog)
  • ✅ No mocks в интеграционных тестах

Frontend (TypeScript)

  • ✅ Next.js App Router
  • ✅ TypeScript strict mode
  • ✅ Auto-generated types из Go structs
  • ✅ Supabase Auth integration

Integration APIs

  • ✅ Crypto2B API integration
  • ✅ Fordefi enterprise custody
  • ✅ Supabase authentication
  • ✅ Webhook processing

Testing

Test Commands

make test                 # Foundation (smoke+unit+core+e2e-smoke)
make test-all             # Full suite (~3 min, 30+ groups)
make smoke                # Critical paths (~30sec)
make unit                 # Go unit tests
make core                 # Integration tests

Test Coverage Targets

  • ✅ API Endpoints: 100% smoke test coverage
  • ✅ Services: >80% unit test coverage
  • ✅ Critical Paths: 100% E2E coverage

Deployment

Local Development

make restart              # Smart restart с пересборкой
make status              # Проверка статуса

VPS Deployment

make deploy              # Blue-Green deployment
make deploy-status       # Статус production
make deploy-rollback     # Откат при проблемах

Production URLs:

  • https://app.saga.surf
  • https://admin.saga.surf
  • https://saga.surf

Development Workflow

Adding New Feature

  1. Research: make context QUERY="feature description"
  2. Plan: Check for duplicates, review architecture
  3. Develop: Follow Clean Architecture, use UnifiedConfig
  4. Test: Unit → Integration → E2E
  5. Document: Update API docs, add examples
  6. Deploy: make commit → make deploy

Fixing Bugs

  1. Diagnose: make analyze, check logs
  2. Write Test: Reproduce bug in test
  3. Fix: Minimal changes, fix root cause
  4. Validate: All tests pass
  5. Deploy: Following standard workflow

For Backend Developers

For Frontend Developers

For Integration Developers

📅 Status

Coverage:

  • ✅ Architecture: 39 docs
  • ✅ Guides: 28 docs
  • ⚠️ API Reference: In Progress (102 endpoints)
  • ⚠️ Onboarding Guide: In Progress

💡 Questions? Create GitHub issue с тегом developer-docs

📋 Метаданные

Версия: 2.4.82

Обновлено: 2025-10-21

Статус: Published