villsim/docs/architecture.md

Архитектура сервера симуляции (Village Sim)

1. Технический стек

Phase 1 (MVP)

• Core: Python 3.11+
• API: FastAPI
• Hot State / Broker: Redis (используется и как БД, и как очередь сообщений)
• Analytics: JSON Logs (файловая система)

Phase 2 (Target Production)

• Analytics: ClickHouse. Для хранения логов каждого хода (Time-Series) и ML-обучения.
• Broker: RabbitMQ / Kafka. Для связи с внешними микросервисами (Внешняя торговля, Auth).
• Metrics: Prometheus + Grafana.

2. Принципы проектирования (Clean Architecture)

Чтобы легко перейти от Phase 1 к Phase 2, жестко соблюдаем слои:

1. Domain Layer (Core): Чистый Python.
   • Бизнес-правила (Entity, Value Objects).
   • Никаких зависимостей от внешних библиотек.
2. Application Layer (Services): Оркестрация.
   • Use Cases ("Сделать ход", "Создать игру").
   • Работает с интерфейсами (IEventBus, IRepository), а не конкретными БД.
3. Infrastructure Layer (Adapters): Грязная реализация.
   • Здесь лежат драйверы Redis, ClickHouse, RabbitMQ.
   • Именно этот слой мы будем менять при масштабировании.

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

4.1. API Gateway (FastAPI)

• Входная точка для клиентов.
• Конвертирует HTTP запросы в Commands.

4.2. Game Engine (Domain)

• TimeSystem: Абстракция времени.
• EntityManager: ECS-структура.
• MarketCore: Логика сведения ордеров.

4.3. Infrastructure Adapters

• RedisGameRepository: Реализация IGameRepository.
• RedisEventBus: Реализация IEventBus (в Phase 2 заменим на KafkaEventBus).
• FileAnalyticsRepository: Реализация IAnalyticsRepository (в Phase 2 заменим на ClickhouseRepository).

5. Поток данных (Data Flow)

1. Action: Клиент шлет POST /action.
2. Bus: API кладет команду в IEventBus (Redis).
3. Worker:
   • Поднимает состояние из IGameRepository.
   • Применяет логику Домена.
   • Генерирует события (FoodEaten, ItemCrafted).
4. Analytics: События асинхронно пишутся в IAnalyticsRepository (ClickHouse/Files).

6. Структура проекта

/app
  /domain           # ЧИСТАЯ ЛОГИКА
    /entities       # Agent, Resource
    /interfaces     # Абстракции: IGameRepository, IEventBus, IAnalytics
    /events         # Domain Events
  
  /application      # СЦЕНАРИИ
    /commands       # DTO
    /use_cases      # GameLoopService
  
  /infrastructure   # РЕАЛИЗАЦИЯ
    /redis          # RedisRepo, RedisBus
    /clickhouse     # (Заготовка) ClickhouseAnalytics
    /fs             # FileAnalytics
  
  /web              # API
    /api            # Routes
    
  main.py           # Dependency Injection Container