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

Frontend Architecture - Saga Project

ОБЗОР АРХИТЕКТУРЫ

Saga проект использует современную frontend архитектуру с упрощенной структурой, оптимизированную для Docker deployment и эффективной разработки.

ОСНОВНЫЕ ПРИНЦИПЫ

1. UNIFIED SHARED COMPONENTS

frontend/
├── shared/                     # ← ЕДИНЫЙ источник компонентов
│   ├── components/
│   │   ├── UnifiedWeb3Provider.tsx    # Web3 для обоих приложений
│   │   └── SimpleDevDashboard.tsx     # Development debugging
│   └── types/                  # Автогенерированные TypeScript типы
├── user-app/                   # Consumer приложение
└── admin-app/                  # Административное приложение

2. STATIC EXPORT + DOCKER INTEGRATION

  • Static Export: next.config.js с output: 'export' для production
  • Docker Serving: Go backend служит статические файлы через HTTP
  • Host-based Routing: app.saga.local → user-app, admin.saga.local → admin-app

3. WEB3 АРХИТЕКТУРА

// Один провайдер для всех приложений
<UnifiedWeb3Provider 
  config={wagmiConfig} 
  enableProtection={true}
>
  <AppContent />
</UnifiedWeb3Provider>

Ключевые особенности: - ✅ БЕЗ RainbowKit - только чистый Wagmi + native connectors - ✅ Ethereum Provider Protection - предотвращает конфликты расширений - ✅ SSR Совместимость через initialState

АРХИТЕКТУРНЫЕ КОМПОНЕНТЫ

UnifiedWeb3Provider

Расположение: frontend/shared/components/UnifiedWeb3Provider.tsx

Назначение: Единый Web3 провайдер для user-app и admin-app

Ключевые функции: 

interface UnifiedWeb3ProviderProps {
  children: React.ReactNode
  initialState?: State              # SSR поддержка
  config: Config                   # Wagmi конфигурация
  enableProtection?: boolean       # Защита ethereum provider
}

Интеграция: - user-app: ClientProviders.tsx → обертка для всего приложения - admin-app: DynamicProviders.tsx → с initialState поддержкой

SimpleDevDashboard

Расположение: frontend/shared/components/SimpleDevDashboard.tsx

Назначение: Development debugging dashboard для быстрой диагностики

Мониторинг: - ⚛️ React Status: Проверка инициализации React runtime - 🌐 Web3 Status: Ethereum provider availability - 🔐 Auth Status: JWT токены и аутентификация
- 📡 Network Status: Online/offline connectivity

Особенности: 

// Только в development режиме
if (process.env.NODE_ENV !== 'development') {
  return null
}

// Настраиваемое позиционирование
position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
enableToggle: boolean  // Показывать toggle кнопку

Интеграция: - user-app: layout.tsx position="top-right" - admin-app: layout.tsx position="top-left"

ReactRuntimeFix (user-app only)

Расположение: frontend/user-app/src/components/common/ReactRuntimeFix.tsx

Назначение: Исправление React runtime инициализации в static export режиме

Механизм:

  1. Проверяет доступность window.React
  2. При отсутствии - анализирует webpack chunks
  3. Программно инициализирует React из найденных модулей
  4. Валидирует успешность через React fiber проверку

DEVELOPMENT WORKFLOW

Быстрая Диагностика

# 1. Запуск системы
make restart

# 2. Проверка статуса
make status

# 3. Открыть в браузере
http://admin.saga.local:8080/  # Admin app с SimpleDevDashboard (top-left)
http://app.saga.local:8080/    # User app с SimpleDevDashboard (top-right)

Debug Process

  1. SimpleDevDashboard: Проверить статус React/Web3/Auth/Network
  2. Browser Console: Анализировать сообщения ReactRuntimeFix (user-app)
  3. Network Tab: Валидировать API calls и static assets
  4. E2E Tests: Запустить automated validation

ELIMINATED LEGACY COMPONENTS

Удалены следующие проблемные компоненты:

❌ ChunkLoadErrorHandler

  • Проблема: Не решал React runtime проблемы
  • Заменен: ReactRuntimeFix с программной инициализацией

❌ HydrationFix

  • Проблема: Дублировал функциональность и создавал конфликты
  • Заменен: Правильная SSR конфигурация через Next.js

❌ ReactRuntimeFix (лишние дубликаты)

  • Сохранен: Только рабочая версия в user-app
  • Удалено: Неработающие копии и старые подходы

ТЕСТИРОВАНИЕ

E2E Validation

  • react-runtime-fix-validation.spec.ts - проверка ReactRuntimeFix
  • unified-web3-provider-validation.spec.ts - Web3 интеграция
  • hydration-validation.spec.ts - SSR/Static export совместимость

Integration Tests

  • Docker container здоровье
  • HTTP статусы приложений (200 OK)
  • SimpleDevDashboard функциональность

DEPLOYMENT АРХИТЕКТУРА

Static Files Flow

1. Next.js build → static files (.next/static/)
2. Docker COPY → /app/static/ в контейнере  
3. Go backend → HTTP serving static files
4. Nginx → reverse proxy с domain routing

Domain Routing

  • Production: admin.saga.surf / app.saga.surf
  • Development: admin.saga.local:8080 / app.saga.local:8080
  • Backend: Host header анализ в composite_router.go

PERFORMANCE ХАРАКТЕРИСТИКИ

Build Metrics

  • User-app: ~30-45 seconds build time
  • Admin-app: ~25-35 seconds build time
  • Total Docker: ~3 minutes full rebuild
  • Hot Reload: <5 seconds (development)

Runtime Performance

  • React Initialization: <500ms с ReactRuntimeFix
  • Web3 Connection: <2 seconds MetaMask detection
  • Page Load: <1 second static assets serving

MONITORING & DEBUGGING

Development Tools

  • SimpleDevDashboard: Real-time system status
  • Browser DevTools: React, Network, Console analysis
  • E2E Reports: Automated validation results

Production Monitoring

  • Docker Health Checks: Container status
  • HTTP Endpoints: /api/health availability
  • Static Assets: CDN/nginx serving metrics

Документ создан: 2025-08-25
Версия архитектуры: v1.6+ (после frontend simplification)
Статус: Активная архитектура в production