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

{
  "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

{
  "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

{
  "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

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

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

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

Redis operations timeouts

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

Health Check System

Endpoint standard pour tous engines

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

// 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 !" ⚙️🇺🇦