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

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

```cpp
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
```cpp
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 (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

```cpp
// 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
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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**
```cpp
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 :**
```cpp
// 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 :**
```cmake
# 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 :**
```bash
# 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 :**
```cpp
// 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 :**
```cmake
# 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 :**
```cpp
// 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
```cpp
// ✅ 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};
    }
};
```

```cpp
// ❌ 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
```bash
# 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
```cpp
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 :**
```cpp
// ✅ 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 :**
```cpp
// ✅ 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 :**
```cpp
// 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**

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

```json
// 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 :**
```cpp
// 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

```cpp
// 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 :**
```cpp
// 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