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

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