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

Triple Interface Pattern (Architecture Révolutionnaire)

NOUVELLE ARCHITECTURE MODULAIRE - Remplace l'ancienne architecture 10 engines par un système modulaire optimisé pour le développement avec Claude Code.

Les 4 Interfaces Fondamentales

IEngine        → Coordination générale (DebugEngine → HighPerfEngine → DataOrientedEngine)
IModuleSystem  → Stratégie d'exécution (Sequential → Threaded → Multithread → Cluster)
IModule        → Logique métier pure (TankModule.so, EconomyModule.so, FactoryModule.so)
IIO            → Communication (IntraIO → LocalIO → NetworkIO)

Séparation des Responsabilités

IEngine : Orchestration et coordination

• DebugEngine : Développement et test (step-by-step, verbose logging)
• HighPerfEngine : Production optimisée (threading, memory management)
• DataOrientedEngine : Scale massive (SIMD, cluster distribution)

IModuleSystem : Stratégies d'exécution

• SequentialModuleSystem : Debug/test (1 module à la fois)
• ThreadedModuleSystem : Chaque module dans son thread
• MultithreadedModuleSystem : Pool de threads pour tasks
• ClusterModuleSystem : Distribution sur plusieurs machines

IModule : Logique métier pure

class IModule {
    virtual json process(const json& input) = 0;  // PURE FUNCTION
    virtual void initialize(const json& config) = 0;
    virtual void shutdown() = 0;
};

Contraintes strictes :

• 200-300 lignes maximum par module
• Aucune dépendance infrastructure (threading, network, etc.)
• JSON in/out uniquement pour communication
• Logic métier pure sans effets de bord

IIO : Couche transport

• IntraIO : Appel direct (même processus)
• LocalIO : Named pipes/sockets (même machine)
• NetworkIO : TCP/WebSocket (réseau)

Évolution Progressive Sans Régression

// Phase 1 : Prototype
DebugEngine + SequentialModuleSystem + IntraIO
→ Développement ultra-rapide, Claude Code 100% focus logique

// Phase 2 : Optimization
DebugEngine + ThreadedModuleSystem + IntraIO
→ Performance boost sans changer 1 ligne de game logic

// Phase 3 : Production
HighPerfEngine + MultithreadedModuleSystem + LocalIO
→ Scale transparent, TankModule.so inchangé

// Phase 4 : MMO Scale
DataOrientedEngine + ClusterModuleSystem + NetworkIO
→ Distribution massive, même logique métier

Avantage révolutionnaire : Les modules de logique métier (TankModule.so, EconomyModule.so) restent identiques à travers toutes les phases d'évolution !

Contrainte Design Fondamentale : Task-Centric Logic

CRITICAL : Les modules doivent être conçus avec une task-centric logic dès le début pour supporter l'évolution progressive.

Task-Centric Logic Requirements

class IModule {
    virtual json process(const json& task) = 0;  // TASK-CENTRIC DESIGN
    // task = unité de travail atomique, pas state global
    // Permet distribution future sans refactoring
};

Implications design :

• Stateless preferred : Tasks indépendantes autant que possible
• Granularité fine : 1 task = 1 opération logique discrète
• Context minimal : Task contient tout le contexte nécessaire
• Results self-contained : Output complet pour la task

Évolution Progressive Détaillée

Phase 1 : Debug/Prototype

DebugEngine + SequentialModuleSystem + IntraIO

• Execution : Tasks traitées séquentiellement par même thread
• Flow : Module1.process(task1) → Module2.process(task2) → Module3.process(task3)
• Avantage : Debug step-by-step, Claude Code friendly
• Task-centric : Prépare la distribution future

Phase 2 : Optimization

DebugEngine + ThreadedModuleSystem + IntraIO

• Execution : Tasks distribuées par module sur threads dédiés
• Flow : Module1(Thread A), Module2(Thread B) - tasks parallèles
• Avantage : Performance sans changer task logic

Phase 3 : Production

HighPerfEngine + MultithreadedModuleSystem + LocalIO

• Execution : Task queue + worker thread pool
• Flow : Tasks distribuées sur pool selon disponibilité et priorité
• Avantage : Load balancing automatique des tasks

Phase 4 : MMO Scale

DataOrientedEngine + ClusterModuleSystem + NetworkIO

• Execution : Tasks distribuées sur machines différentes
• Flow : TankTasks (Server A), EconomyTasks (Server B)
• Avantage : Scale horizontal transparent grâce au task-centric design

Évolution Garantie : Le task-centric design initial permet l'évolution automatique vers la distribution sans réécriture de logique métier !

Distribution Performance-Based

Classification : CRITICAL - Implémentation immédiate requise Principe : Distribution intelligente basée sur contraintes de performance

Classification des Modules par Performance

Critical Locale (Exécution Locale Obligatoire) :

• ProductionModule : <1ms latence pour 60fps frame-perfect
• TankModule (targeting) : <16ms pour 60Hz combat responsiveness
• UI/Input modules : <5ms pour réactivité utilisateur immédiate

Strategic Distribuée (Distribution Réseau Acceptable) :

• EconomyModule : 1000ms tolérable pour décisions économiques
• MapModule (chunks) : 500ms acceptable pour streaming asynchrone
• Analytics modules : 5000ms+ acceptable pour métriques

Mixed (Performance Contextuelle) :

• LogisticModule : 50ms transport temps réel vs 1000ms planification

Table de Distribution Performance

Module	Type	Latence Max	IIO Optimal	Justification
ProductionModule	Critical	<1ms	IntraIO	60fps frame-perfect requis
TankModule	Critical	<16ms	IntraIO/LocalIO	Combat responsiveness
EconomyModule	Strategic	1000ms	NetworkIO	Décisions tolèrent délai
MapModule	Strategic	500ms	NetworkIO	Streaming asynchrone
LogisticModule	Mixed	50-1000ms	LocalIO/NetworkIO	Context-dependent

Implications Utilisateurs

Performance garantie :

• Responsivité critique preservée : Factory/combat toujours fluides (local)
• Scaling transparent : Ajout joueurs sans impact performance locale
• Adaptation réseau automatique : Qualité connexion n'affecte pas gameplay core
• Mode dégradé intelligent : Basculement local si réseau défaillant

Expérience utilisateur optimisée :

• Latence imperceptible : Actions critiques feedback instantané
• Bandwidth efficient : Seuls modules strategic utilisent réseau
• Offline capability : Modules critical fonctionnent sans connexion
• Performance prévisible : Expérience identique solo vs multiplayer

Implications Développeurs

Architecture optimisée Claude Code :

• Classification dès design : Contraintes performance explicites par module
• Debugging simplifié : Modules critical toujours accessibles localement
• Testing isolé : Performance testing sans infrastructure réseau
• Build autonome : Profiling performance intégré par module

Workflow développement :

• Distribution automatique : IIO routing basé sur profil performance
• Evolution progressive : Migration Critical→Strategic selon optimisation
• Profiling précis : Métriques performance par catégorie module
• Context minimal : Focus logique métier pure, classification implicite

Intégration Triple Interface

IIO Performance-Aware Routing :

// Automatic routing based on module performance profile
if (module.latencyRequirement < 1ms) {
    use IntraIO;  // Critical - same process
} else if (module.latencyRequirement < 50ms) {
    use LocalIO;  // Mixed - same machine
} else {
    use NetworkIO;  // Strategic - distributed
}

Migration transparente par phases :

• Phase 1 (Dev) : Tous modules IntraIO pour debugging
• Phase 2 (Prod) : Critical IntraIO, Strategic LocalIO
• Phase 3 (MMO) : Critical IntraIO, Strategic NetworkIO worldwide

Build Autonome par Module

Classification : HIGH - Implémentation prioritaire Principe : cmake . depuis chaque module, zéro dépendance parent

Structure de Build Autonome

Directory pattern requis :

modules/tank/
├── CMakeLists.txt       # Autonomous build config
├── CLAUDE.md           # Module-specific instructions
├── src/
│   ├── TankModule.cpp  # 200 lignes max
│   └── TankModule.h    # Interface pure
├── tests/
│   └── tank_test.cpp   # Standalone testing
└── build/             # Local build artifacts
    └── tank.so        # Hot-reloadable module

CMake autonome pattern :

# NEVER cmake .. - ALWAYS cmake .
cmake_minimum_required(VERSION 3.20)
project(TankModule)

# Self-contained dependencies
find_package(nlohmann_json REQUIRED)

# Pure module compilation
add_library(tank MODULE src/TankModule.cpp)
target_link_libraries(tank nlohmann_json::nlohmann_json)

# Standalone testing
add_executable(tank-test tests/tank_test.cpp)
target_link_libraries(tank-test tank)

Implications Utilisateurs

Performance développement révolutionnaire :

• Build ultra-rapide : 5 secondes vs 5 minutes (60x faster)
• Debugging isolé : Test module sans infrastructure complète
• Parallélisme naturel : Multiple builds simultanés sans conflit
• Stabilité accrue : Modification module N n'affecte jamais module M

Expérience développeur optimisée :

• Context switching minimal : Focus total sur logique module
• Error isolation parfaite : Compilation errors localisées uniquement
• Testing granulaire : Validation unitaire immédiate et autonome
• Hot-reload ready : Module.so prêt pour remplacement instantané

Implications Développeurs

Architecture modulaire pure :

• Zero dependencies up : Jamais #include "../core/engine.h"
• Self-contained units : Chaque module = micro-projet autonome
• Interface contracts only : Communication via JSON/IModule uniquement
• Infrastructure agnostic : Module ignore engine/system hosting

Workflow Claude Code révolutionnaire :

• Micro-context focus : 200-300 lignes + CMakeLists.txt + CLAUDE.md total
• Parallel instances : 3+ Claude Code travaillant simultanément
• Build verification : cmake . && make validation automatique
• Development velocity : 10x improvement mesurable

Contraintes Strictes CRITICAL

NEVER patterns (violations = build failure) :

• cd .. ou cmake .. - Toujours rester dans module directory
• #include "../" - Aucune référence parent directory
• Dependency sur core/ ou shared/ - Module = island complet
• Shared C++ objects - JSON communication exclusive

ALWAYS patterns (required for autonomy) :

• cd modules/tank/ && cmake . - Build depuis module directory
• Interface-only dependencies - IModule.h via find_package uniquement
• Local build artifacts - build/ directory dans module
• Standalone testing - Tests s'exécutent sans infrastructure

Métriques de Performance

Metric	Avant (Monolithe)	Après (Autonome)	Amélioration
Build time	2-5 min	<5 sec	24-60x faster
Context size	50K+ lignes	200-300 lignes	250x smaller
Parallel dev	1 instance	3+ instances	3x+ throughput
Error isolation	Project-wide	Module-only	Perfect isolation
Iteration cycle	5-10 min	5 sec	60-120x faster

Hot-Reload Infrastructure

Classification : HIGH - Implémentation prioritaire Principe : Remplacement temps réel modules DLL/SO avec sauvegarde état

Architecture Hot-Reload

Platform Support :

• Primary : .dll (Windows gaming natif)
• Future : .so (Linux server/dev support)
• Unified interface : Même mécanisme, extension différente

Workflow cible :

# Edit TankModule.cpp → Save → Auto-rebuild tank.dll
# Système détecte changement → Hot-reload → Game continue
# <5 secondes total sans interruption

Mécanisme Technique

Windows DLL Hot-Reload :

// State preservation avant reload
json moduleState = currentModule->exportState();

// Hot-swap DLL
FreeLibrary(tankDLL);                    // Décharge ancienne
tankDLL = LoadLibrary(L"tank.dll");      // Charge nouvelle version

// State restoration après reload
auto createFunc = GetProcAddress(tankDLL, "CreateTankModule");
newModule = createFunc();
newModule->importState(moduleState);     // Restore état

Build DLL autonome :

# modules/tank/CMakeLists.txt
add_library(tank SHARED src/TankModule.cpp)
set_target_properties(tank PROPERTIES
    SUFFIX ".dll"                        # Windows primary
    POSITION_INDEPENDENT_CODE ON         # Linux SO ready
)

Implications Utilisateurs

Développement révolutionnaire :

• Feedback instantané : Changements visibles immédiatement sans restart
• Flow state preserved : Concentration maintenue, zéro interruption
• Session continuity : Données de jeu préservées pendant développement
• Real-time testing : Validation changements en contexte réel

Expérience gameplay optimisée :

• Config tweaking live : Modification paramètres à chaud
• Balance updates instant : Ajustements gameplay sans redémarrage
• Bug fixes immediate : Corrections appliquées en temps réel
• A/B testing dynamic : Switch comportements dynamiquement

Implications Développeurs

Workflow ultra-optimisé :

• Edit → Save → Test : Cycle 5 secondes vs 5 minutes (60x faster)
• State preservation : Contexte développement totalement maintenu
• Debug facilité : Isolation précise des changements
• Experimentation rapide : Testing hypothèses ultra-rapide

Architecture requirements :

• State serialization : JSON export/import complet état module
• Interface stability : IModule contracts préservés pendant reload
• Memory safety : Cleanup automatique ancien module, zéro leak
• Thread safety : Hot-swap sans race conditions

File Watching & Auto-Rebuild

Monitoring automatique :

// File system watcher
FileWatcher watcher("modules/tank/");
watcher.onChange("*.cpp", [](){
    rebuildModule("tank");
    hotReloadModule("tank.dll");
});

Build pipeline intégré :

• Change detection : .cpp modification trigger auto-build
• Compilation rapide : Module isolé <5 sec build
• Success validation : Hot-reload seulement si build réussi
• Error handling : Fallback ancien module si échec

Contraintes & Performance

Requirements techniques :

• Interface compatibility : IModule contracts identiques pre/post reload
• State serializability : Toutes données JSON-serializable
• No static globals : État encapsulé dans instances module
• Export functions : CreateModule, DestroyModule standardisées

Performance impact :

• Reload time : <5 secondes garantis (target <2 sec)
• Runtime overhead : <1% en production (hot-reload disabled)
• Memory usage : Temporairement doublé pendant transition
• Gaming performance : Zéro impact, Windows DLL natif

Contrainte Claude Code : Micro-Context Optimization

CRITICAL : Modules limités à 200-300 lignes maximum pour optimiser l'efficacité de développement avec Claude Code.

Problème Résolu : Context Window

• Avant : Claude Code doit comprendre 50K+ lignes interconnectées
• Après : Claude Code travaille sur modules isolés de 200-300 lignes max
• Résultat : 250x réduction de la complexité contextuelle

Contraintes Strictes de Taille

• MAX 300 lignes par fichier module
• Target 200-250 lignes optimal pour Claude Code
• ~200K tokens maximum context window Claude Code
• 280 lignes typiquement utilisées (CLAUDE.md + Module.cpp + Interface.h)

Architecture Micro-Context

// ✅ CORRECT - Module optimisé Claude Code
class TankModule : public IModule {
    json process(const json& task) override {
        // 200 lignes de pure tank logic
        // Aucune infrastructure, networking, threading
        // JSON in/out uniquement
        return {"status": "moving", "position": newPos};
    }
};

// ❌ INCORRECT - Trop complexe pour Claude Code
class MegaTankSystem {
    // 5000+ lignes avec networking, threading, UI, etc.
    // Claude Code ne peut pas appréhender efficacement
};

Workflow Révolutionnaire : Développement Parallèle

# Instance Claude Code A - 280 lignes context
cd modules/tank/
# Context: CLAUDE.md (50) + TankModule.cpp (200) + IModule.h (30)

# Instance Claude Code B - 250 lignes context
cd modules/economy/
# Context: CLAUDE.md (70) + EconomyModule.cpp (150) + IModule.h (30)

# Instance Claude Code C - 230 lignes context
cd modules/factory/
# Context: CLAUDE.md (60) + FactoryModule.cpp (140) + IModule.h (30)

Contexte Ultra-Simple Garantit

• Zéro infrastructure dans le contexte Claude Code
• Information hiding : Claude ne voit jamais l'architecture complète
• Focus 100% sur logique métier pure
• Build autonome : cmake . depuis le module

Avantages Claude Code Mesurés

• Iteration rapide : 5 secondes vs 5-10 minutes traditional
• Compréhension parfaite : Context entièrement maîtrisable par IA
• Quality boost : Focus intense sur logique pure
• Parallel instances : 3+ Claude Code travaillant simultanément
• Development velocity : 10x improvement démontré

Modules Principaux

L'architecture modulaire remplace les anciens engines par des modules spécialisés, chacun implémentant l'interface IModule avec logique métier pure.

ProductionModule

• Responsabilité : Production Factorio-like (Belt + Inserter + Factory intégré)
• Scope : Mining, assemblage, transport items, stockage
• Contrainte : Monolithe nécessaire pour performance frame-perfect (60fps)
• Communication : JSON avec LogisticModule pour export/import

EconomyModule

• Responsabilité : Simulation économique, marchés, pricing dynamique
• Scope : Agent-based economy, supply/demand, transport optimization
• Business Models : Arbitrage, Market Making, Transport Optimization
• Communication : JSON market data, price updates

TankModule

• Responsabilité : Comportement véhicules de combat
• Scope : Movement, targeting, combat states, damage calculation
• Performance : 60Hz targeting, 30Hz movement, 1Hz tactical
• Communication : JSON commands, state updates

LogisticModule

• Responsabilité : Transport goods, supply chains
• Scope : Route optimization, convoy management, infrastructure
• Economic Integration : Cost-based transport mode selection
• Communication : JSON transport requests, delivery confirmations

MapModule

• Responsabilité : Terrain, procedural generation, FOW
• Scope : Multi-scale maps, chunk streaming, 218+ generation elements
• Performance : Lazy loading, memory management
• Communication : JSON terrain queries, chunk data

Architecture Communication

Communication Modulaire

Protocole uniforme : JSON-only entre tous les modules via interfaces IIO

Architecture Client/Server Modulaire

Classification : CRITICAL - Implémentation immédiate requise Evolution progressive : V1 Thin Client → V2 Shared Logic

Phase V1 : Thin Client Validation

Architecture :

• Client display-only, toute logique côté serveur
• Validation authoritative centralisée
• Communication via NetworkIO pour toutes les décisions

Performance Targets (Points 98-103) :

• V1 Client Target : 30+ fps stable (Point 98)
• V1 Server Capacity : 10+ concurrent players (Point 100)
• V1 Latency : <150ms validation acceptable (Point 102)

Pour les utilisateurs :

• Latence perceptible : 50-150ms délai entre action et feedback
• Connexion requise : Impossibilité de jouer hors ligne
• Synchronisation garantie : Aucune désynchronisation possible

Pour les développeurs :

• Développement simplifié : Une seule source de vérité côté serveur
• Debug facilité : Toute la logique centralisée et traçable
• Sécurité native : Anti-cheat par design via validation serveur
• Déploiement rapide : Architecture simple, mise en production directe

Phase V2 : Shared Logic Prediction

Architecture :

• Logique métier partagée client/serveur
• Prédiction locale avec réconciliation serveur
• Communication optimisée via NetworkIO intelligent

Performance Targets (Points 99-103) :

• V2 Client Target : 60+ fps avec prediction (Point 99)
• V2 Server Capacity : 100+ concurrent players (Point 101)
• V2 Network : 30ms server, 0ms perceived client (Point 103)

Pour les utilisateurs :

• Latence zéro perçue : Feedback instantané via prédiction locale
• Mode hors ligne : Gameplay possible avec synchronisation différée
• Performance optimale : 60fps avec prédiction fluide
• Expérience premium : Réactivité comparable aux jeux locaux

Pour les développeurs :

• Complexité accrue : Synchronisation client/serveur à gérer
• Logic partagée : Modules identiques côté client et serveur
• Testing avancé : Validation prédiction + réconciliation
• Migration progressive : Évolution V1→V2 sans réécriture complète

Métriques de Performance

Phase	Latence Perçue	FPS Client	Capacité Serveur	Mode Offline
V1	50-150ms	30+ fps	10+ joueurs	Non
V2	0ms (prédiction)	60+ fps	100+ joueurs	Oui

Intégration Architecture Modulaire

Distribution intelligente :

• Critical modules (ProductionModule) : Toujours locaux pour 60fps
• Strategic modules (EconomyModule) : Distribués selon tolérance latence
• War modules : V1 serveur, V2 client avec réconciliation

Migration sans risque (Point 10) : Évolution sans risque architecture client/server

• Pattern hot-swappable : Transition V1→V2 transparente pour modules
• A/B testing : Validation progressive par groupes d'utilisateurs (10% → 50% → 100%)
• Fallback automatique : Retour V1 en cas d'échec V2
• Zéro réécriture : V1 code reste valide, V2 = extension progressive
• Forward-compatible : Architecture V1 compatible V2 dès le design initial

Exemple migration progressive :

// Code adaptable V1/V2 sans réécriture
if (config.enable_v2_prediction) {
    // V2: Client prediction + server validation
} else {
    // V1: Server authoritative (fallback sûr)
}

Communication standardisée :

• JSON exclusivement : Interface uniforme client/serveur
• NetworkIO évolutif : Support V1 et V2 simultané
• State preservation : Continuité état durant migration

Stack Technique Modulaire

• IntraIO : Communication intra-processus (développement/debug)
• LocalIO : Named pipes/sockets (même machine, production)
• NetworkIO : TCP/WebSocket avec support V1/V2 client/server

Patterns Communication

• Modules → JSON in/out : Interface pure, pas de dépendances directes
• Hot-reload compatible : Communication préservée durant updates modules
• Client/Server agnostic : Même logique métier, déploiement différent selon phase

Avantages Architecture Modulaire

Développement Claude Code Optimisé

• Contextes micro : 200-300 lignes par module vs 50K+ lignes système monolithique
• Build autonome : cd modules/tank/ && cmake . - zéro dépendance parent
• Hot-reload : Modifications instantanées sans restart système
• Développement parallèle : Multiple instances Claude Code simultanées

Performance & Scalabilité

• Évolution progressive : Debug → Production → MMO sans réécriture
• Module isolation : Failures localisées, pas de cascade
• Infrastructure hot-swappable : Change performance sans affecter logique métier

Maintenance & Evolution

• Testing isolé : Chaque module testable indépendamment
• Migration zero-risk : A/B testing, fallback automatique
• Code reuse : Modules réutilisables entre projets