# Архитектура сервера симуляции (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. Структура проекта

```text
/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
```