warfactoryracine/docs/architecture-technique.md

# Architecture Technique

## Vision Globale

**Concept** : RTS/4X hybride hommageant l'Ukraine avec système industriel complexe (Factorio-like), simulation militaire réaliste et gestion géopolitique.

**Innovation clé** : Architecture multi-serveurs modulaire permettant scaling horizontal et développement parallèle par IA.

## Architecture Système

### Structure Modulaire Multi-Serveurs

```
                    ┌─────────────────────┐
                    │  Central Coordinator │  ← Meta orchestrator (bootstrap, health, lifecycle)
                    └─────────────────────┘
                                │
    ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
    │       │       │       │       │       │       │       │       │       │       │
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│Fact │ │Logic│ │Econ │ │Desig│ │Macro│ │ Map │ │Comb │ │Oper │ │Intel│ │Event│
│ory  │ │istic│ │omy  │ │ner  │ │Enti │     │ │ at  │ │ation│ │ li  │     │
└─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘
    │       │       │       │       │       │       │       │       │       │
    └───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┘
            │       │       │       │       │       │       │       │
      ┌─────────────────────────────────────────────────────────────┐
      │                        Clients                              │ ← Smart UI/Rendering, Authoritative Server
      └─────────────────────────────────────────────────────────────┘
```

## Engines Autonomes

### Définition Autonomie
L'architecture repose sur 10 engines autonomes communicant via APIs standardisées, chacun responsable d'un domaine spécifique du gameplay.

**Autonome signifie** :
- ✅ **Logique métier** : Calculs, décisions, algorithmes dans son domaine
- ✅ **State persistence** : Gère ses données en mémoire/disque
- ✅ **Graceful degradation** : Continue de fonctionner si autres engines down
- ✅ **Independent scaling** : Peut être optimisé/étendu séparément

**Autonome ne signifie PAS** :
- ❌ **Infrastructure isolée** : Utilise services communs (metrics, health, config)
- ❌ **Communication zero** : Échange données via Redis/HTTP selon besoins
- ❌ **No dependencies** : Utilise données d'autres engines (prix, terrain, etc.)

**Timing interactions** :
- **Critique temps réel** : Direct HTTP GET (ex: War Engine → Map Engine terrain)
- **Background sync** : Redis Pub/Sub async (ex: Economy → tous engines prix)
- **Infrastructure services** : HTTP à demande (ex: Intelligence Engine métriques)

### Vue d'ensemble Engines

### Factory Engine
- **Responsabilité** : Systèmes Factorio du joueur uniquement
- **Scope** : Mining, production, assemblage, infrastructures joueur
- **Autonomie** : Simulation complète des usines joueur
- **Communication** : Export données production vers Logistic Engine

### Logistic Engine
- **Responsabilité** : Flux physiques et virtuels de ressources
- **Scope** : Transport, supply chains, FOBs militaires, distribution
- **Autonomie** : Gestion complète des mouvements de biens
- **Communication** : Interface avec Factory, Economy et Combat Engines

### Economy Engine
- **Responsabilité** : Usines IA, marchés, prix dynamiques
- **Scope** : Productions IA, company behaviors, marchés segmentés
- **Autonomie** : Simulation économique globale indépendante
- **Communication** : Prix/demandes vers tous engines consommateurs

### Designer System Engine
- **Responsabilité** : Design véhicules procédural pour IA + assistance joueur
- **Scope** :
  - Design procédural IA : random generation + evaluate + pass/drop
  - Assistance design joueur : même système utilisable manuellement
  - Blueprints doctrinaux : grilles efficaces, designs dev, captures enemy
  - Modification designs existants vs création from scratch
- **Autonomie** :
  - Engine autonome répondant aux commandes joueur + IA
  - Random ticking génération avec évaluation viabilité basique
  - Company features influencent choix procéduraux
- **Évaluation Designs** :
  - Check stats sur CDC théorique ("design viable ?")
  - Détection automatique designs défaillants (tank 1km/h = reject)
  - Long-term : Retex spécifiques d'Operation Engine (anti-Javelin urbain)
  - Future : Combat simulations via War Engine
- **Communication** :
  - Reçoit demandes Operation Engine + joueur
  - Nouveaux designs vers Economy et War Engines
  - Blueprints évolutifs inter-companies (captures)
- **Spécialité** : Inclut système de recherche dual et breakthroughs

### MacroEntity Engine (Company & State)
- **Responsabilité** : Entités (companies, états), diplomatie, points administration
- **Scope** :
  - Features companies, relations, politiques commerciales
  - Système points administration pour companies et états
  - Actions coûtant admin : recherche, commerce, diplomatie, production, militaire
- **Autonomie** : Comportements entités, évolution features, gestion pools admin quotidiens
- **Communication** : Commandes vers Economy, restrictions vers tous engines
- **Points Administration** :
  - Pool quotidien companies (1000 base) et états (variable selon taille)
  - Actions bloquées si admin exhausté (pas de queue, refus immédiat)
  - Modificateurs via company features et contexte (guerre, récession)
  - Calculs légers, batch processing, rythme bas adapté gameplay macro

### Map Engine
- **Responsabilité** : Gestion carte, streaming, génération
- **Scope** : Chunks, FOW, navigation, terrain procedural
- **Autonomie** : Génération à la demande, optimisation mémoire
- **Communication** : Données terrain vers Combat et Factory Engines

### Combat Engine (War Engine)
- **Responsabilité** : Auto-battler tactique avec stocks embarqués
- **Scope** :
  - Batailles temps réel avec ~500 unités actives simultanées
  - Last meter logistics (camions, dépôts locaux, 3km radius)
  - Stocks munitions/carburant dans véhicules et dépôts tactiques
  - Zones trigger pour défense automatique
- **Autonomie** :
  - Self-contained avec propres stocks et round de commande
  - Unités agissent avec derniers ordres reçus si communication coupée
  - Gestion autonome logistique courte distance
- **Communication** :
  - Reports situation brute vers Operation Engine (pull par waves)
  - Intel bâtiments vers Intelligence Engine
  - Demandes resupply vers Logistic Engine (longue distance)
  - Updates Economy Engine post-bataille (délai acceptable ~1 minute)

### Operation Engine
- **Responsabilité** : IA militaire décisionnelle et coordination organisationnelle
- **Scope** :
  - Analyse rapports War Engine pour "comprendre" situations (méthode TBD)
  - Génération ordres tactiques et stratégiques
  - Coordination avec politique via Economy Engine
  - Doctrines militaires différenciées par nation/company
- **Autonomie** :
  - Vraie IA militaire (analyse, compréhension, décision)
  - Peut créer latence décisionnelle réaliste (France 1940)
  - Gestion orders de bataille (test → attaque → exploitation)
- **Machine Learning Simple** :
  - Apprentissage tactiques efficaces par contexte/terrain/véhicules
  - Retex par général avec influence modèles nationaux (doctrines)
  - Évolution doctrinale lente vs apprentissage général rapide
  - Résistance convergence par diversité tech/armes semi-random
- **Coordination Politique** :
  - Reçoit objectifs stratégiques du politique (Economy Engine)
  - Politique peut override directions militaires
  - Adaptation militaire aux contraintes politiques
- **Communication** :
  - Reçoit reports du War Engine
  - Envoie ordres au War Engine
  - Reçoit objectifs stratégiques Economy Engine
  - Demandes intel à Intelligence Engine

### Intelligence Engine
- **Responsabilité** : Reconnaissance, espionnage, fog of war, métriques économiques
- **Scope** : Satellites, intel gathering, information warfare, collecte métriques
- **Autonomie** : Collecte et analyse renseignements, agrégation data économique
- **Communication** : Intel vers Operation et Company Engines
- **Métriques multijoueur** : Scaling adaptatif selon nombre companies, data sharing intelligent

### Event Engine
- **Responsabilité** : Événements aléatoires, crises, disruptions
- **Scope** : Wars, breakthroughs, economic crashes, endgame crisis
- **Autonomie** : Déclenchement et gestion événements contextuels
- **Communication** : Trigger events vers engines concernés

## Architecture Communication Inter-Engines

### Stack Technique
- **Redis Pub/Sub** : Communication asynchrone événementielle (pull par waves)
- **HTTP REST** : Queries synchrones et commands
- **JSON** : Format d'échange uniforme
- **TCP** : Reliability pour données critiques

### Principe de Communication
- **War Engine** : Self-contained, pulls par waves (évite spam messages)
- **Latence assumée** : Délais logistiques intégrés au gameplay (réalisme)
- **Autonomie engines** : Continuent à fonctionner avec dernières données reçues
- **Reports non temps réel** : Economy updates acceptent délais 1+ minute

### Patterns Redis par Engine

#### Factory Engine
**PUBLISHES** :
```
factory:production_complete   → Economy, Logistic
factory:shutdown             → Logistic, Map
factory:resource_request     → Economy, Logistic
factory:blueprint_test       → Designer
```

**SUBSCRIBES** :
```
economy:price_update         ← Economy
logistic:resource_available  ← Logistic
designer:blueprint_ready     ← Designer
```

#### Economy Engine
**PUBLISHES** :
```
economy:price_update         → Factory, Combat, Logistic
economy:market_crash         → ALL
economy:company_bankrupt     → Company&State, Map
economy:resource_shortage    → Factory, Logistic
```

**SUBSCRIBES** :
```
factory:production_complete  ← Factory
combat:battle_result         ← Combat
logistic:transport_complete  ← Logistic
company:order_placed         ← Company&State
```

#### Combat Engine
**PUBLISHES** :
```
combat:battle_start          → Economy, Map, Intelligence
combat:battle_result         → Economy, Map, Intelligence, Operation
combat:unit_destroyed        → Economy, Logistic
combat:resource_consumed     → Economy, Logistic
```

**SUBSCRIBES** :
```
economy:price_update         ← Economy
logistic:supply_delivered    ← Logistic
operation:battle_order       ← Operation
intelligence:enemy_spotted   ← Intelligence
```

#### Map Engine
**PUBLISHES** :
```
map:territory_change         → ALL
map:resource_discovered      → Economy, Factory
map:terrain_updated          → Combat, Logistic
map:fog_revealed             → Intelligence, Operation
```

**SUBSCRIBES** :
```
factory:shutdown             ← Factory
combat:battle_result         ← Combat
intelligence:recon_complete  ← Intelligence
```

#### Logistic Engine
**PUBLISHES** :
```
logistic:transport_complete  → Economy, Factory
logistic:supply_delivered    → Combat
logistic:resource_available  → Factory
logistic:convoy_attacked     → Combat, Economy
```

**SUBSCRIBES** :
```
factory:production_complete  ← Factory
combat:resource_consumed     ← Combat
economy:resource_shortage    ← Economy
map:terrain_updated          ← Map
```

#### Designer Engine
**PUBLISHES** :
```
designer:blueprint_ready     → Factory, Economy
designer:tech_breakthrough   → ALL
designer:design_validated    → Economy, Combat
```

**SUBSCRIBES** :
```
factory:blueprint_test       ← Factory
combat:performance_data      ← Combat
economy:market_demand        ← Economy
```

#### MacroEntity Engine (Company & State)
**PUBLISHES** :
```
macroentity:order_placed         → Economy
macroentity:feature_changed      → Economy, Designer
macroentity:diplomatic_action    → ALL
macroentity:policy_change        → Economy, Map
macroentity:admin_exhausted      → Economy (action refusée)
```

**SUBSCRIBES** :
```
economy:company_bankrupt     ← Economy
combat:battle_result         ← Combat
event:crisis_triggered       ← Event
economy:action_request       ← Economy (check admin disponible)
```

#### Operation Engine
**PUBLISHES** :
```
operation:battle_order       → War Engine
operation:strategy_change    → War Engine, Logistic
operation:target_selected    → War Engine, Intelligence
operation:resupply_request   → Logistic
```

**SUBSCRIBES** :
```
war:situation_report         ← War Engine (pull par waves)
intelligence:intel_update    ← Intelligence
economy:political_directive  ← Economy (political coordination)
```

#### War Engine (Combat Engine)
**PUBLISHES** :
```
war:situation_report         → Operation Engine (waves, non temps réel)
war:building_discovered      → Intelligence
war:resupply_needed         → Logistic
war:battle_complete         → Economy (délai 1+ min acceptable)
```

**SUBSCRIBES** :
```
operation:battle_order       ← Operation Engine
logistic:supply_delivered    ← Logistic (long distance resupply)
map:terrain_updated          ← Map
```

#### Intelligence Engine
**PUBLISHES** :
```
intelligence:enemy_spotted   → Combat, Operation
intelligence:intel_update    → Operation, Company&State
intelligence:recon_complete  → Map, Operation
```

**SUBSCRIBES** :
```
combat:battle_start          ← Combat
map:fog_revealed             ← Map
```

#### Event Engine
**PUBLISHES** :
```
event:crisis_triggered       → ALL
event:breakthrough_event     → Designer, Economy
event:diplomatic_crisis      → Company&State
```

**SUBSCRIBES** :
```
(Monitore all channels pour trigger contextuel)
```

### APIs HTTP Standardisées

#### Format URL Standard
```
http://{engine-name}:808{N}/{endpoint}

Ports :
factory:8080, economy:8081, combat:8082, map:8083
logistic:8084, designer:8085, macroentity:8086, operation:8087
intelligence:8088, event:8089
```

#### Endpoints Communs (tous engines)
```
GET  /health              → Health check
GET  /status              → État général engine
GET  /metrics             → Métriques performance
POST /shutdown            → Arrêt propre engine
```

#### Endpoints Spécifiques par Engine

**Factory Engine** :
```
GET  /factories           → Liste usines actives
GET  /factories/{id}      → Détails usine
POST /factories/{id}/start → Démarrer production
POST /factories/{id}/stop  → Arrêter production
GET  /production/queue     → Queue production
POST /blueprints/validate  → Valider blueprint
```

**Economy Engine** :
```
GET  /prices              → Prix actuels toutes ressources
GET  /prices/{resource}   → Prix ressource spécifique
GET  /market/demand       → Demande par ressource
GET  /companies           → Liste companies actives
POST /orders              → Placer commande
```

**Combat Engine** :
```
GET  /battles/active      → Batailles en cours
POST /battles/start       → Démarrer bataille
GET  /units/status        → Status toutes unités
POST /units/{id}/order    → Donner ordre unité
```

### Format JSON Uniforme

#### Structure Standard Message
```json
{
  "timestamp": "2024-03-15T14:30:00Z",
  "source_engine": "factory",
  "target_engines": ["economy", "logistic"],
  "event_type": "production_complete",
  "sequence_id": 12345,
  "data": {
    "factory_id": "fact_001",
    "produced_item": "steel_plate",
    "quantity": 100,
    "quality": 85
  },
  "metadata": {
    "priority": "normal",
    "retry_count": 0
  }
}
```

#### Format HTTP Response Standard
```json
{
  "success": true,
  "timestamp": "2024-03-15T14:30:00Z",
  "engine": "economy",
  "data": {
    "steel_price": 45.0,
    "trend": "increasing"
  },
  "error": null,
  "execution_time_ms": 23
}
```

#### Format Error Standard
```json
{
  "success": false,
  "timestamp": "2024-03-15T14:30:00Z",
  "engine": "combat",
  "data": null,
  "error": {
    "code": "UNIT_NOT_FOUND",
    "message": "Unit with ID unit_123 not found",
    "details": {
      "unit_id": "unit_123",
      "requested_action": "move"
    }
  },
  "execution_time_ms": 5
}
```

### Flux de Données Critiques
```
Factory Engine → Economy/Logistic : Production outputs
Economy Engine → ALL : Prix et demandes
Designer Engine → Economy/Combat : Nouveaux designs
Intelligence Engine → Operation : Reconnaissance data
Event Engine → ALL : Crisis triggers
Map Engine → Combat/Factory : Terrain data
Operation Engine → Combat : Battle orders
Combat Engine → Economy/Map : Battle results
```

## Error Handling & Reliability

### Engine Crash/Restart Strategy

**Detection rapide de crash**
```
Health check HTTP: GET /health toutes les 30 secondes
Redis heartbeat: PUBLISH engine:heartbeat {"engine": "factory", "timestamp": "..."}
Timeout detection: Si pas de heartbeat depuis 60s = engine down
```

**Recovery automatique**
```
Engine redémarre → republish état current dans Redis
Example: Factory Engine restart → PUBLISH factory:status {"active_productions": [...]}
Autres engines reçoivent l'update et ajustent leur état local
```

**Graceful degradation**
```cpp
// Dans chaque engine
if (!canReachEngine("economy")) {
    // Utiliser derniers prix connus en cache
    price = fallbackPriceCache.get(resource);
    logWarning("Using cached price, Economy engine unreachable");
}
```

### Redis Failover Strategy

**Redis persistence activée**
```
# Configuration Redis
save 900 1     # Save snapshot if 1+ keys changed in 15min
appendonly yes # Log toutes les commandes
```

**Multiple Redis instances** (plus tard)
```
Primary Redis: 6379 (read/write)
Replica Redis: 6380 (read-only backup)
Si primary down → engines switch automatiquement vers replica
```

**Message replay après Redis restart**
```
Chaque engine garde buffer local des derniers messages
Engine restart → replay buffer vers Redis pour resync
```

### Circuit Breaker Pattern

**Éviter cascade failures**
```cpp
class EngineCircuitBreaker {
    int failureCount = 0;
    bool isOpen = false;

    bool callEngine(string endpoint) {
        if (isOpen && failureCount > 5) {
            return false; // Circuit ouvert, pas d'appel
        }

        if (httpCall(endpoint).success()) {
            failureCount = 0; // Reset sur succès
            return true;
        } else {
            failureCount++;
            if (failureCount > 5) isOpen = true;
            return false;
        }
    }
}
```

### Message Persistence & Replay

**Event sourcing basique**
```
Redis streams pour persistence:
XADD events:factory * engine factory event production_complete data {...}
XADD events:combat * engine combat event battle_end data {...}

Recovery: XREAD depuis last timestamp connu
```

**State snapshots**
```
Chaque engine sauvegarde état complet périodiquement:
HSET snapshots:factory:1234567890 state "{...complete_state...}"
Recovery = load last snapshot + replay events depuis timestamp
```

### Timeout & Retry Strategy

**HTTP calls avec timeouts**
```cpp
HttpConfig config {
    .connectionTimeout = 5000ms,  // 5s pour établir connection
    .requestTimeout = 10000ms,    // 10s pour réponse complète
    .retryCount = 3,
    .retryDelay = 1000ms
};
```

**Redis operations timeouts**
```cpp
RedisConfig config {
    .commandTimeout = 2000ms,    // 2s max par commande Redis
    .reconnectRetryInterval = 5000ms
};
```

### Health Check System

**Endpoint standard pour tous engines**
```json
GET /health
Response:
{
  "status": "healthy|degraded|unhealthy",
  "dependencies": {
    "redis": "connected",
    "other_engines": ["factory:healthy", "economy:degraded"]
  },
  "metrics": {
    "uptime": 3600,
    "requests_per_second": 45,
    "error_rate": 0.02
  }
}
```

**Central monitoring simple**
```
Script qui poll /health de tous engines toutes les 30s
Log les status changes
Alert si engine down > 2 minutes
```

## Détails des Engines

### Factory Engine
- **Responsabilité** : Systèmes Factorio du joueur uniquement
- **Scope** : Mining, production, assemblage, infrastructures joueur
- **Autonomie** : Simulation complète des usines joueur
- **Communication** : Export données production vers Logistic Engine
- **Innovation** : Factory benchmarking → conversion stable factories en lookup tables
- **Performance** : Unload simulation détaillée après stabilisation

### Logistic Engine
- **Responsabilité** : Flux physiques et virtuels de ressources
- **Scope** : Transport, supply chains, FOBs militaires, distribution
- **Autonomie** : Gestion complète des mouvements de biens
- **Communication** : Interface avec Factory, Economy et Combat Engines
- **Features** : Transport multi-modal (camions, trains, avions, drones, navires)
- **Vulnérabilités** : Convois attaquables, infrastructure destructible

### Economy Engine
- **Responsabilité** : Usines IA, marchés, prix dynamiques
- **Scope** : Productions IA, company behaviors, marchés segmentés
- **Autonomie** : Simulation économique globale indépendante
- **Communication** : Prix/demandes vers tous engines consommateurs
- **Features** : Système économique réactif aux événements militaires
- **Marchés** : National, company-specific, blocs, mondial avec restrictions

### Designer System Engine
- **Responsabilité** : Conception IA de véhicules et équipements
- **Scope** : Algorithmes design, validation, recherche technologique
- **Autonomie** : Processus design distribué, cultural blueprints
- **Communication** : Nouveaux designs vers Economy et Combat Engines
- **Spécialité** : Inclut système de recherche dual et breakthroughs
- **Performance** : 1-2 designs créés globalement par tick (total mondial, pas par company), évolution vs création from scratch

### MacroEntity Engine (Company & State)
- **Responsabilité** : Entités (companies, états), diplomatie, points administration
- **Scope** : Features companies, relations, politiques commerciales, système admin
- **Autonomie** : Comportements entités, évolution features, gestion admin pools
- **Communication** : Commandes vers Economy, restrictions vers tous
- **Features** : Système 2-4 features par company, évolution dynamique
- **Diplomatie** : Relations internationales, sanctions, embargos
- **Administration** : Pool quotidien, actions bloquées si exhausté, modificateurs contextuels

### Map Engine
- **Responsabilité** : Gestion carte, streaming, génération
- **Scope** : Chunks, FOW, navigation, terrain procedural
- **Autonomie** : Génération à la demande, optimisation mémoire
- **Communication** : Données terrain vers Combat et Factory Engines
- **Système** : Zoom discret (global + local 1mx1m), chunks 64x64
- **Navigation** : Node-based pour terrestre, libre pour aérien

### Combat Engine
- **Responsabilité** : Batailles temps réel, IA militaire
- **Scope** : Unités, doctrines, combats locaux
- **Autonomie** : Simulations tactiques indépendantes
- **Communication** : Résultats vers Map et Logistic Engines
- **Performance** : Adaptive tick rate (60→15 TPS sous charge)
- **Features** : Actions normales (assaut, reco, soutien, etc.)

### Operation Engine
- **Responsabilité** : Opérations militaires, généraux IA
- **Scope** : Stratégie macro, AI decision making, planning
- **Autonomie** : Prise de décision stratégique autonome
- **Communication** : Ordres vers Combat Engine, demandes vers Logistic
- **Features** : Généraux avec ML, doctrines, expérience terrain
- **IA** : Adaptation comportements selon succès/échecs

### Intelligence Engine
- **Responsabilité** : Reconnaissance, espionnage, fog of war
- **Scope** : Satellites, intel gathering, information warfare
- **Autonomie** : Collecte et analyse renseignements
- **Communication** : Intel vers Operation et Company Engines
- **Système** : FOW par chunks, qualité reconnaissance progressive
- **Persistance** : Mémoire intel par actor, expiration possible

### Event Engine
- **Responsabilité** : Événements aléatoires, crises, disruptions
- **Scope** : Wars, breakthroughs, economic crashes, endgame crisis
- **Autonomie** : Déclenchement et gestion événements contextuels
- **Communication** : Trigger events vers engines concernés
- **Features** : 3 endgames (zombies, aliens, démons), events géopolitiques
- **Probabilités** : Events égales entre companies, adaptation contextuelle

### Central Coordinator
- **Fonction** : Meta orchestrator - bootstrap, health monitoring, lifecycle management
- **Scope ultra-limité** :
  - Lancement engines + load map/gameset initial
  - Health ping engines (pas leur contenu)
  - Time sync basique si nécessaire
  - Graceful shutdown + unload map (quit partie)
- **Aveugle au gameplay** : Ne connaît rien des mécaniques de jeu, pure infrastructure
- **Post-bootstrap** : Engines communiquent directement via Redis, coordinator passif
- **Crash-safe** : Coordinator down = invisible pour gameplay, engines continuent autonomes

## Décisions Techniques Clés

### 1. Performance Stack
- **Langages** : C++ / C / ASM pour performance critique
- **Justification** : Simulation temps réel complexe + milliers d'unités
- **Compromise** : Complexité dev acceptable vs performance requirements

### 2. Synchronisation Multijoueur
- **Problème** : Déterminisme impossible avec multi-serveurs
- **Solution** : Server-authoritative + error-resilient design
- **Approach** : Graceful degradation + periodic sync + rollback capability

### 3. Smart Client / Authoritative Server
- **Client Smart** : Interface complexe, rendu optimisé, streaming carte, cache local
- **Client Dumb** : Aucune simulation gameplay, pas de logique métier
- **Server Authoritative** : Toute simulation et état de jeu sur serveurs
- **Avantages** : Anti-cheat naturel, interface réactive, pas de sync client-side
- **Trade-off** : Latency interactions vs sécurité et cohérence

### 4. Async Gameplay Design
- **Principe** : Combat peut avoir latence, player gère autre chose
- **Implémentation** : Background processing pendant que player fait diplo/éco
- **Exemple** : Bataille 10k unités = 30 secondes → player continue production

## Optimisations Performance


### Load Management
- **Adaptive Tick Rate** : 60 TPS → 15 TPS si surcharge
- **Queue Systems** : Batch processing pour opérations coûteuses
- **Future Scaling** : Clustering dynamique per module

## Workflow Développement

### IA-Assisted Development
- **Claude Code #1** → Factory Engine + Logistic Engine
- **Claude Code #2** → Combat Engine + Operation Engine
- **Claude Code #3** → Economy Engine + Designer Engine
- **Claude Code #4** → MacroEntity Engine + Intelligence Engine
- **Claude Code #5** → Map Engine + Event Engine
- **Humain** → Central Coordinator + architecture globale + vision produit

### Principe Modulaire pour IA
- **Self-contained modules** → Claude peut "faire du spagos" dans sa boîte
- **Clean APIs** → interfaces claires entre modules
- **Isolation** → bugs dans un module n'affectent pas les autres

## Repository Structure

```
Ukraine-War-Game/                    # Meta-repository
├── Factory-Engine/                  # Git submodule
├── Logistic-Engine/                 # Git submodule
├── Economy-Engine/                  # Git submodule
├── Designer-Engine/                 # Git submodule
├── MacroEntity-Engine/              # Git submodule
├── Map-Engine/                      # Git submodule
├── Combat-Engine/                   # Git submodule
├── Operation-Engine/                # Git submodule
├── Intelligence-Engine/             # Git submodule
├── Event-Engine/                    # Git submodule
├── Client-Renderer/                 # Git submodule
├── Central-Coordinator/             # Git submodule
├── shared/                         # Protocols & configs communs
│   ├── engine-apis/                # Interface contracts entre engines
│   ├── message-schemas/            # Format des messages inter-engines
│   └── event-definitions/          # Types d'événements standardisés
├── docs/                           # Documentation architecture
├── scripts/                        # Dev tools (build-all, deploy)
└── docker/                         # Dev environment setup
```

## Scalabilité Future

### Clustering Capability
- **Current** : 1 serveur par module
- **Future** : N serveurs per module avec load balancing
- **Implementation** : Kubernetes orchestration + auto-scaling

### Performance Monitoring
- **Health Checks** : Inter-server communication monitoring
- **Metrics** : Tick rates, queue sizes, response times
- **Alerting** : Auto-failover + human notifications

## Considérations Multijoueur

### Sync Strategy
- **Error-Resilient** : Accept temporary inconsistencies
- **Periodic Reconciliation** : Checkpoints + state correction
- **Conflict Resolution** : Server priority rules + rollback capability

### Network Architecture
- **Server-to-Server** : Reliable message queues (Redis/RabbitMQ)
- **Client-to-Server** : Standard TCP/WebSocket
- **Client Responsibilities** :
  - Rendu 2D pixel art avec LOD et culling
  - Interface utilisateur complexe (industrielle, militaire, diplomatique)
  - Streaming carte intelligent (zoom, position, cache zones explorées)
  - Cache local pour performance UI
- **Server Authority** : Simulation, logique métier, état de jeu
- **Bandwidth** : Clients reçoivent state updates, n'envoient que commands

## Art Direction & Rendering

### Style Visuel : Pixel Art
- **Justification** : Prototypage rapide, génération par IA (Claude), performance optimale
- **Aesthetic** : Factorio-like, RTS classique, lisibilité maximale
- **Avantages développement** :
  - Claude capable de générer sprites cohérents par batch
  - Itération rapide sur feedback visuel
  - Pas de complexité 3D/animation
  - Style intemporel et scalable

### Spécifications Assets
- **Véhicules** : 32x32 pixels (chars, IFV, drones)
- **Bâtiments** : 64x64 pixels (usines, défenses)
- **Terrain** : Tiles 32x32 (sol, routes, végétation)
- **UI Elements** : Pixel perfect, zoom discret (1x, 2x, 4x)
- **Color Palette** : Limitée pour cohérence (à définir selon contexte Ukraine)

## Roadmap Technique

### Phase 1 : Core Engines MVP
- [ ] Factory Engine (mining + production basique)
- [ ] Economy Engine (resources tracking)
- [ ] Map Engine (chunks + navigation basique)
- [ ] Client renderer pixel art (tech stack TBD)

### Phase 2 : Multi-Engine Integration
- [ ] Central Coordinator implementation
- [ ] Inter-engine communication protocols (message queues)
- [ ] Logistic Engine (transport basique)
- [ ] Combat Engine (unit battles simple)

### Phase 3 : Advanced Engines
- [ ] Designer Engine (IA vehicle conception)
- [ ] MacroEntity Engine (entities + diplomatie + administration)
- [ ] Operation Engine (généraux IA)
- [ ] Intelligence Engine (FOW + reconnaissance)

### Phase 4 : Complete System
- [ ] Event Engine (crises + événements)
- [ ] Factory benchmarking system
- [ ] Performance optimizations (adaptive tick rate)
- [ ] Endgame crisis implementations

## Notes de Conception

### Pragmatisme vs Perfection
- **Principle** : Ship working system > perfect architecture
- **Error Strategy** : Resilient design > error-free design
- **Performance** : Good enough > premature optimization

### Hommage Ukraine
- **Lore** : Guerre réelle comme base narrative
- **Valeurs** : Mettre en avant courage et liberté ukrainiens
- **Authenticity** : Systèmes militaires basés sur conflit réel

---

**"Ave Machina, guide my development !"** ⚙️🇺🇦