aissia/docs/01-architecture/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

Core Interface Architecture

ARCHITECTURE MODULAIRE - Système modulaire optimisé pour le développement avec Claude Code.

Les 5 Interfaces Fondamentales

ICoordinationModule → Orchestrateur global système (MainServer, déploiement, config)
IEngine            → Coordination locale (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)

Architecture de Déploiement Global

MainServer Process:
├── CoordinationModule (Global Orchestrator)
│   ├── Loads gameconfig.json via IDataTree
│   ├── Manages local IEngine + modules
│   └── Launches remote servers + engines
├── Local IEngine (manages local modules)
│   ├── IModuleSystem (Sequential/Threaded/etc.)
│   └── Local Modules (.so files)
└── Remote Servers (launched by coordination)
    ├── Remote IEngine (manages remote modules)
    ├── IModuleSystem (execution strategy)
    └── Remote Modules (.so files)

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

ICoordinationModule : Orchestrateur global système

• Premier module lancé, dernier fermé
• Charge gameconfig.json via IDataTree
• Déploie modules selon topologie (local/distant)
• Synchronise configurations entre tous les modules

IModule : Logique métier pure (BREAKING CHANGES)

class IModule {
    virtual json process(const json& input) = 0;  // PURE FUNCTION
    virtual void setConfiguration(const IDataNode& configNode, IIO* io, ITaskScheduler* scheduler) = 0;  // NEW
    virtual const IDataNode& getConfiguration() = 0;  // NEW
    virtual json getHealthStatus() = 0;  // NEW - detailed JSON instead of bool
    virtual void shutdown() = 0;
    // initialize() method REMOVED
};

Contraintes strictes :

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

Exception ProductionModule :

• Belt+Inserter+Factory DOIVENT cohabiter dans le même module pour performance critique
• 500-800 lignes acceptées pour ce module spécifiquement
• Raison : ISocket overhead >1ms inacceptable pour production 60 FPS
• Trade-off conscient : Complexité accrue mais performance garantie

Décomposition War en Subsystèmes Asynchrones

Principe : Le module War décomposé en subsystèmes avec fréquences d'exécution différentes

Subsystèmes identifiés :

• Targeting : Acquisition et tracking des cibles (haute fréquence)
• Movement : Déplacement et physique des unités (fréquence moyenne)
• Pathfinding : Calcul des routes optimales (à la demande)
• Tactical : Décisions tactiques et IA (basse fréquence)
• Analytics : Métriques et statistiques de combat (très basse fréquence)

Avantages de la désynchronisation :

• Performance : Chaque système tourne à sa fréquence optimale
• Scalabilité : Distribution possible sur threads/cores différents
• Modularité : Systèmes indépendants plus faciles à maintenir
• Réactivité : Systèmes critiques (targeting) restent fluides

Tolérance Réseau War :

• 50-100ms de latence acceptable pour décisions stratégiques
• Combat n'est pas frame-perfect comme un FPS
• Synchronisation relaxée suffisante pour RTS/stratégie
• Permet joueurs avec connexions moyennes

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
• Unit tests intégrés - #ifdef TESTING validation autonome modules
• Behavior composition - Modules comportements combinables via config JSON

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

Performance Scaling Architecture (Point 39)

Hiérarchie temporelle optimisée pour balance performance/complexité :

4 Tiers Performance

enum PerformanceTier {
    LOCAL_REALTIME,      // Transport mode selection (real-time)
    REGIONAL_HOURLY,     // Market clearing (hourly)
    ECONOMIC_DAILY,      // Complex modeling (daily)
    INFRASTRUCTURE_MONTHLY // Long-term investment (monthly)
};

Local Decisions (Real-time)

• Target : 60fps gameplay garanti
• Scope : Factory production, transport mode selection, player input
• Constraint : Zero network latency impact
• Budget : 16ms per frame maximum

Regional Coordination (Hourly)

• Target : Market clearing operations
• Scope : Order matching, price updates, transport assignment
• Tolerance : 50-100ms network delays acceptable
• Budget : 5-10 seconds processing time

Economic Simulation (Daily)

• Target : Complex economic modeling
• Scope : Demographics, market volatility, AI behaviors
• Frequency : 0.01-0.1Hz processing
• Budget : Up to 30 seconds computation acceptable

Infrastructure Planning (Monthly)

• Target : Long-term strategic calculations
• Scope : ROI analysis, regional development, policy changes
• Tolerance : High latency, batch processing
• Budget : Several minutes computation acceptable

Architecture Benefits :

• Performance isolation : Critical path (60fps) protected from complex simulation
• Resource allocation : CPU budget approprié per tier
• Network optimization : Frequency matching network tolerance
• Modular scaling : Each module operates at optimal frequency
• 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)
• Frequency : 60Hz processing pour frame-perfect timing
• War Isolation : ZERO interaction directe avec WarModule/TankModule
• Communication : JSON avec LogisticModule pour export/import uniquement

EconomyModule

• Responsabilité : Simulation économique, marchés, pricing dynamique
• Scope : Agent-based economy, supply/demand, transport optimization
• Frequency : 0.01-0.1Hz (cycles économiques lents)
• 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
• Frequency : 0.1-60Hz (Targeting 60Hz → Movement 30Hz → Tactical 1Hz → Analytics 0.1Hz)
• Factory Isolation : Aucune interaction directe avec ProductionModule
• Turret Supply : Approvisionnement via LogisticModule uniquement
• Communication : JSON commands, state updates

LogisticModule

• Responsabilité : Transport goods, supply chains, turret supply
• Scope : Route optimization, convoy management, infrastructure, war asset supply
• Frequency : Variable (50ms temps réel → 1000ms planification)
• War Integration : Approvisionne turrets/war assets, PAS inserters directs
• 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
• Frequency : Variable selon context (streaming asynchrone)
• Performance : Lazy loading, memory management

Module Frequencies & Isolation Rules

Frequency Specifications (Points 109-125)

Performance-Critical Modules :

• ProductionModule : 60Hz (frame-perfect factory operations)
• TankModule Targeting : 60Hz (combat responsiveness)
• TankModule Movement : 30Hz (position updates)

Strategic Modules :

• TankModule Tactical : 1Hz (strategic decisions)
• TankModule Analytics : 0.1Hz (long-term analysis)
• EconomyModule : 0.01-0.1Hz (economic cycles)

Context-Dependent Modules :

• LogisticModule : 50ms (real-time) → 1000ms (planning)
• MapModule : Asynchronous (on-demand streaming)

Isolation Rules (Points 133-134)

War Module Isolation :

// ✅ CORRECT - War assets via LogisticModule
LogisticModule → TurretSupply → Ammunition
LogisticModule → VehicleSupply → Fuel/Parts

// ❌ FORBIDDEN - Direct factory interaction
ProductionModule → TankModule  // ZERO interaction
FactoryInserter → Turret       // NO direct supply

ProductionModule Isolation :

// ✅ CORRECT - Only LogisticModule interface
ProductionModule ↔ LogisticModule  // Export/Import only
LogisticModule ↔ WarModule        // Supply war assets

// ❌ FORBIDDEN - Any direct war interaction
ProductionModule ↔ TankModule     // ZERO interaction
ProductionModule ↔ TurretModule   // ZERO interaction

Supply Chain Architecture :

• Factory → Logistics → War (unidirectional flow)
• NO shortcuts : Direct factory-to-war connections prohibited
• Reason : Module isolation, testability, hot-reload safety
• 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

Development Philosophy & Patterns

Point 51 : Backward Compatibility Framework

Proxy pattern ancien→nouveau coexistence

// Backward compatibility via proxy pattern
class LegacyTankAdapter : public IModule {
    std::unique_ptr<OldTankSystem> legacySystem;
    std::unique_ptr<NewTankModule> modernSystem;
    bool useModern = false;

public:
    json process(const json& input) override {
        if (useModern && modernSystem->isReady()) {
            try {
                return modernSystem->process(input);
            } catch (const std::exception&) {
                // Fallback to legacy on failure
                return legacySystem->processLegacy(convertToOldFormat(input));
            }
        }
        return legacySystem->processLegacy(convertToOldFormat(input));
    }

    void enableModernSystem() { useModern = true; }
    void fallbackToLegacy() { useModern = false; }
};

Benefits Architecture :

• Zero-risk migration : Ancien système reste fonctionnel
• A/B testing : Switch runtime entre old/new
• Progressive rollout : Migration progressive users
• Instant rollback : Retour automatique si problème

Point 52 : YAGNI Modding Philosophy

Pas modding pre-release, config system suffit 90% cas

Philosophy : Configuration-driven flexibility plutôt que modding infrastructure complexe

// Config-driven "modding" via JSON
{
  "tank_variants": {
    "tank_mk1": {
      "health": 100,
      "speed": 35,
      "armor": "medium",
      "weapons": ["cannon_75mm"]
    },
    "tank_mk2_custom": {
      "health": 150,
      "speed": 30,
      "armor": "heavy",
      "weapons": ["cannon_105mm", "mg_coaxial"]
    }
  },
  "behavior_mods": {
    "aggressive_ai": {
      "engagement_range": 1000,
      "retreat_threshold": 20,
      "target_priority": "closest"
    }
  }
}

Architecture Benefits :

• 90% modding needs : Config JSON couvre la majorité des besoins
• Zero complexity : Pas infrastructure modding complexe
• Claude-friendly : Config changes = instant AI comprehension
• Runtime modification : Hot-reload configs sans restart

Future Extension :

// When modding eventually needed (post-release)
class ModdingInterface : public IModule {
    json process(const json& input) override {
        // Modding hooks will be added here later
        // For now, config-driven behavior is sufficient
        return processConfigDriven(input);
    }
};

Point 53 : "Complexity through Simplicity"

AAA complexité via modules simples Claude-friendly

Core Philosophy : Complex gameplay emerges from interaction of simple, well-designed modules

// Simple tank module (200 lines)
class TankModule : public IModule {
    json process(const json& input) override {
        // Simple tank behavior: move, shoot, retreat
        return processSimpleTankLogic(input);
    }
};

// Simple economy module (250 lines)
class EconomyModule : public IModule {
    json process(const json& input) override {
        // Simple market: supply, demand, price discovery
        return processSimpleMarket(input);
    }
};

// Complex gameplay emerges from interaction
// Tank + Economy = Resource-constrained warfare
// Tank + Factory = Production-line optimization
// Economy + Factory = Industrial economic simulation

Emergent Complexity Examples :

Simple Rules → Complex Behavior :

// Rule 1: Tanks need fuel (EconomyModule)
// Rule 2: Fuel costs money (MarketModule)
// Rule 3: Money comes from production (FactoryModule)
// Rule 4: Production needs resources (LogisticModule)

// Emergent behavior: Complex supply-chain warfare
// Players must balance factory output, resource extraction,
// economic planning, and military operations

Architecture Benefits :

• Claude comprehension : Each module easily understood by AI
• Debugging simplicity : Issues isolated to specific modules
• Testing granularity : Simple modules = simple tests
• Development velocity : Small contexts = fast iteration

AAA Complexity Achieved Through :

• Module interaction : Simple rules create complex systems
• Configuration depth : JSON configs add sophistication
• Emergent gameplay : Player strategies emerge naturally
• Progressive revelation : Complexity unlocked gradually