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

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

**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
- **Performance moindre** : 30fps stable mais pas optimal

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

**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 :**
- **Pattern hot-swappable** : Transition V1→V2 transparente pour modules
- **A/B testing** : Validation progressive par groupes d'utilisateurs
- **Fallback automatique** : Retour V1 en cas d'échec V2

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