Architecture Overview

⚠️ Документация в процессе наполнения

Общая архитектура GOLOOT

Компоненты системы

Стек технологий

Слой	Технология	Почему выбрано
Backend	Fastify + TypeScript	TODO
ORM	Prisma	TODO
Database	PostgreSQL	TODO
Cache	Redis	TODO
Frontend	React + Vite	TODO
State	Zustand + TanStack Query	TODO
Bot	grammy	TODO

---

Loading System

LoadingOrchestrator Pattern

Централизованное управление состоянием загрузки через LoadingOrchestrator компонент (frontend).

Ключевая идея: Системные проверки (maintenance, season) выполняются до загрузки Bootstrap, чтобы предотвратить бесполезные запросы к БД и показать правильный UI сразу.

Loading Hierarchy

System-Level vs Business-Level Checks

Уровень	Шаг	Проверка	Блокирует Bootstrap?	Пример
System	STEP 0	Maintenance Mode	✅ Да	Технические работы
System	STEP 0.5	Season Availability	✅ Да	Нет активного сезона
Business	STEP 1-N	Onboarding (Bot, Subscription)	✅ Да	Активация бота
Data	Final	Bootstrap (Profile, Cases, Quests, etc.)	—	8 параллельных запросов

Критическое отличие:

• System-level — проверяют доступность всей системы (без активного сезона игры нет)
• Business-level — проверяют состояние конкретного пользователя (активирован ли бот)

Graceful Degradation Principle

Правило: Если проверка упала с ошибкой — не блокировать пользователя.

// ✅ ПРАВИЛЬНО: при ошибке возвращаем безопасный default
try {
  const status = await checkMaintenance();
  return { isActive: status.isActive, bypassed: status.bypassed };
} catch (error) {
  console.error('Check failed:', error);
  return { isActive: false };  // Не блокируем пользователя
}

// ❌ НЕПРАВИЛЬНО: при ошибке блокируем всех
try {
  const status = await checkMaintenance();
  return status;
} catch (error) {
  throw error;  // Приложение не загрузится для ВСЕХ пользователей
}

Зачем: Предотвращает ситуацию, когда баг в системной проверке (или временная недоступность API) блокирует доступ всем пользователям.

Loading States

Все состояния загрузки определены в frontend/src/types/loading.types.ts:

export type AppLoadingState =
  | 'idle'                    // Ничего не загружается
  | 'checking_maintenance'    // ШАГ 0
  | 'checking_season'         // ШАГ 0.5
  | 'creating_session'        // Onboarding
  | 'checking_bot'
  | 'checking_subscription'
  | 'activating_session'
  | 'loading_profile'
  | 'checking_ban'
  | 'loading_bootstrap';      // Финальная загрузка данных

Каждое состояние имеет человекочитаемое сообщение в LOADING_MESSAGES.

Resource Savings

Сценарий	Без Early Checks	С Early Checks	Экономия
Maintenance активен	Bootstrap (8 запросов) + показ overlay	Только /api/maintenance/status → overlay	~8 DB queries, ~200ms
Season неактивен	Bootstrap (8 запросов) + 503 ошибки + overlay	Только /api/seasons/current → overlay	~8 DB queries, ~200ms
Нормальная работа	Bootstrap	2 проверки + Bootstrap	+~100ms (незначительно)

Итог: Early checks добавляют ~100ms в нормальном режиме, но экономят ~200ms + снимают нагрузку с БД в критичных ситуациях.

Files

Файл	Назначение
frontend/src/components/LoadingOrchestrator.tsx	Управление загрузкой, системные проверки
frontend/src/types/loading.types.ts	Типы состояний загрузки
frontend/src/components/MaintenanceOverlay.tsx	Overlay для maintenance mode
frontend/src/components/SeasonCountdownOverlay.tsx	Overlay для inter-season периодов
frontend/src/hooks/useMaintenance.ts	React Query hook для maintenance
frontend/src/hooks/useSeason.ts	React Query hook для season

---

Связанные документы

• Domain Structure — стандарт структуры домена (эталон: achievements)
• Common Structure — стандарт структуры common/ директории
• Observability — логирование, метрики, трейсинг (Loki, Prometheus, Tempo)
• Security Matrix — сводная матрица защит по всем доменам
• Redis Integration — стратегия использования Redis
• Tier System — единая система редкости предметов
• Docs Deployment — CI/CD для документации
• Data Sync — синхронизация данных TMA ↔ Backend (Bootstrap, SSE, Optimistic Updates)

Планируется:

• Tech Stack Decisions