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 │  ← Event ordering & health monitoring
                    └─────────────────────┘
                                │
    ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐
    │       │       │       │       │       │       │       │       │       │       │
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│Fact │ │Logic│ │Econ │ │Desig│ │Comp │ │ Map │ │Comb │ │Oper │ │Intel│ │Event│
│ory  │ │istic│ │omy  │ │ner  │ │any  │     │ │ at  │ │ation│ │ li  │     │
└─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘
    │       │       │       │       │       │       │       │       │       │
    └───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┼───────┘
            │       │       │       │       │       │       │       │
      ┌─────────────────────────────────────────────────────────────┐
      │                        Clients                              │ ← Dumb terminals (rendering only)
      └─────────────────────────────────────────────────────────────┘
```

## Engines Autonomes

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

### 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é** : 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

### Company & State Engine
- **Responsabilité** : Entités (companies, états), diplomatie
- **Scope** : Features companies, relations, politiques commerciales
- **Autonomie** : Comportements entités, évolution features
- **Communication** : Commandes vers Economy, restrictions vers tous

### 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
- **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

### 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

### 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

### 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
- **HTTP REST** : Queries synchrones et commands
- **JSON** : Format d'échange uniforme
- **TCP** : Reliability pour données critiques

### 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
```

#### Company & State Engine
**PUBLISHES** :
```
company:order_placed         → Economy
company:feature_changed      → Economy, Designer
company:diplomatic_action    → ALL
state:policy_change          → Economy, Map
```

**SUBSCRIBES** :
```
economy:company_bankrupt     ← Economy
combat:battle_result         ← Combat
event:crisis_triggered       ← Event
```

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

**SUBSCRIBES** :
```
combat:battle_result         ← Combat
intelligence:intel_update    ← Intelligence
logistic:supply_status       ← Logistic
```

#### 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, company: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 tetris par tick, évolution vs création from scratch

### Company & State Engine
- **Responsabilité** : Entités (companies, états), diplomatie
- **Scope** : Features companies, relations, politiques commerciales
- **Autonomie** : Comportements entités, évolution features
- **Communication** : Commandes vers Economy, restrictions vers tous
- **Features** : Système 2-4 features par company, évolution dynamique
- **Diplomatie** : Relations internationales, sanctions, embargos

### 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** : Event ordering, health checks, failover management
- **Solution Sync** : Logical sequences (pas timestamps) pour éviter clock sync issues
- **Pattern** : Error-resilient architecture over error-free
- **Communication** : Interface avec tous les 10 engines pour coordination

## 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. Clients = Dumb Terminals
- **Avantage** : Pas de sync client-side, anti-cheat naturel
- **Inconvénient** : Latency pour interactions
- **Justification** : Strategy game → latency acceptable vs RTS pur

### 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

### Factory Benchmarking System
```cpp
// Pseudo-code concept
if (factory.isStable() && factory.benchmarkComplete()) {
    // Lookup table - ultra rapide
    output = productionTable.calculate(inputs);
} else {
    // Full simulation - précis mais coûteux
    output = detailedSimulation.process(inputs);
}
```

**Process** :
1. Factory neuve → full simulation détaillée
2. Après X cycles stables → benchmark input/output ratios
3. Conversion en lookup table → unload detailed simulation
4. Recalibrage si modifications (upgrades, dégâts)

### 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** → Company&State 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
├── CompanyState-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
- **Bandwidth** : Clients reçoivent state updates, n'envoient que commands

## Roadmap Technique

### Phase 1 : Core Engines MVP
- [ ] Factory Engine (mining + production basique)
- [ ] Economy Engine (resources tracking)
- [ ] Map Engine (chunks + navigation basique)
- [ ] Client renderer (WebGL/OpenGL)

### 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)
- [ ] CompanyState Engine (entities + diplomatie)
- [ ] 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 !"** ⚙️🇺🇦