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

```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
- **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

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

#### 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
- **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 :**
```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