From 0720dde31f6b279f650d87ed4b51a5d531c51716 Mon Sep 17 00:00:00 2001
From: Maxim Snesarev <snesarev1317@gmail.com>
Date: Sun, 18 Jan 2026 16:04:36 +0300
Subject: [PATCH] Add architecture documentation for Village Sim, outlining
 technical stack, design principles, system components, data flow, and project
 structure.

---
 docs/architecture.md | 78 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..fde6e75
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,78 @@
+# Архитектура сервера симуляции (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
+```