warfactoryracine/docs/01-architecture/architecture-modulaire.md

Architecture Modulaire - Warfactory

Concept Révolutionnaire

L'architecture modulaire Warfactory transforme le développement de jeux complexes en utilisant une approche micro-modules optimisée pour Claude Code. Chaque module est un micro-contexte de 200-300 lignes de logique métier pure.

Triple Interface Pattern

Architecture Fondamentale

IEngine        → Orchestration et coordination
IModuleSystem  → Stratégies d'exécution
IModule        → Logique métier pure
IIO            → Communication et transport

IEngine - Orchestration

Responsabilité : Coordination générale du système et évolution performance

class IEngine {
public:
    virtual void initialize() = 0;
    virtual void update(float deltaTime) = 0;
    virtual void shutdown() = 0;
    virtual void setModuleSystem(std::unique_ptr<IModuleSystem>) = 0;
};

Implémentations disponibles :

• 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

Responsabilité : Détermine comment et quand les modules s'exécutent

class IModuleSystem {
public:
    virtual void registerModule(const std::string& name, std::unique_ptr<IModule>) = 0;
    virtual void processModules(float deltaTime) = 0;
    virtual void setIOLayer(std::unique_ptr<IIO>) = 0;
    virtual json queryModule(const std::string& name, const json& input) = 0;
};

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

Responsabilité : Logique de jeu spécialisée sans infrastructure

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

    // Hot-reload support
    virtual json getState() = 0;                     // Save state
    virtual void setState(const json& state) = 0;    // Restore state
};

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

Responsabilité : Abstraction transport entre modules

class IIO {
public:
    virtual json send(const std::string& target, const json& message) = 0;
    virtual json receive(const std::string& source) = 0;
    virtual void broadcast(const json& message) = 0;
};

Implémentations transport :

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

Modules Spécialisés

ProductionModule (Exception Critique)

Particularité : Belt+Inserter+Factory DOIVENT cohabiter pour performance

class ProductionModule : public IModule {
    // EXCEPTION: 500-800 lignes acceptées
    // Raison: ISocket overhead >1ms inacceptable pour 60 FPS

    Belt beltSystem;
    Inserter inserterSystem;
    Factory factorySystem;

public:
    json process(const json& input) override {
        // Frame-perfect coordination required
        auto beltData = beltSystem.update(input);
        auto inserterData = inserterSystem.update(beltData);
        auto factoryData = factorySystem.update(inserterData);

        return factoryData;
    }
};

TankModule

class TankModule : public IModule {
    // Targeting: 60Hz
    // Movement: 30Hz
    // Tactical: 1Hz
    // Analytics: 0.1Hz

public:
    json process(const json& input) override {
        auto context = getCurrentContext(input);

        if (shouldUpdateTargeting(context)) {
            return processTargeting(input);  // 60Hz
        }

        if (shouldUpdateMovement(context)) {
            return processMovement(input);   // 30Hz
        }

        if (shouldUpdateTactical(context)) {
            return processTactical(input);   // 1Hz
        }

        return processAnalytics(input);      // 0.1Hz
    }
};

EconomyModule

class EconomyModule : public IModule {
    // Economic cycles: 0.01-0.1Hz

public:
    json process(const json& input) override {
        auto marketData = input["market"];

        // Slow economic simulation
        auto priceUpdates = calculatePriceDiscovery(marketData);
        auto supplyDemand = updateSupplyDemand(marketData);
        auto transportOptim = optimizeTransportCosts(marketData);

        return {
            {"prices", priceUpdates},
            {"supply_demand", supplyDemand},
            {"transport", transportOptim}
        };
    }
};

LogisticModule

class LogisticModule : public IModule {
    // Variable frequency: 50ms → 1000ms

public:
    json process(const json& input) override {
        auto context = input["context"];

        if (context["urgent"]) {
            return processRealTimeTransport(input);  // 50ms
        }

        return processPlanning(input);               // 1000ms
    }
};

Isolation et Communication

Règles d'Isolation Strictes

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

Supply Chain Architecture :

// ✅ CORRECT - Unidirectional flow
ProductionModule ↔ LogisticModule  // Export/Import only
LogisticModule ↔ WarModule        // Supply war assets

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

Communication JSON

Standard Message Format :

{
  "timestamp": 1234567890,
  "source": "TankModule",
  "target": "LogisticModule",
  "action": "request_supply",
  "data": {
    "item": "ammunition",
    "quantity": 100,
    "priority": "high"
  }
}

Response Format :

{
  "timestamp": 1234567891,
  "source": "LogisticModule",
  "target": "TankModule",
  "status": "completed",
  "data": {
    "delivered": 100,
    "eta": "30s",
    "cost": 50.0
  }
}

Hot-Reload Architecture

State Preservation

class TankModule : public IModule {
private:
    json persistentState;

public:
    json getState() override {
        return {
            {"position", currentPosition},
            {"health", currentHealth},
            {"ammunition", ammunitionCount},
            {"target", currentTarget}
        };
    }

    void setState(const json& state) override {
        currentPosition = state["position"];
        currentHealth = state["health"];
        ammunitionCount = state["ammunition"];
        currentTarget = state["target"];
    }
};

Hot-Reload Workflow

class ModuleLoader {
    void reloadModule(const std::string& modulePath) {
        // 1. Save state
        auto state = currentModule->getState();

        // 2. Unload old module
        unloadModule(modulePath);

        // 3. Load new module
        auto newModule = loadModule(modulePath);

        // 4. Restore state
        newModule->setState(state);

        // 5. Continue execution
        registerModule(newModule);
    }
};

Claude Code Development

Workflow Optimisé

# 1. Claude travaille dans contexte isolé
cd modules/tank/
# Context: CLAUDE.md (50 lignes) + TankModule.cpp (200 lignes) + IModule.h (30 lignes)
# Total: 280 lignes vs 50K+ dans architecture monolithique

# 2. Development cycle ultra-rapide
edit("src/TankModule.cpp")  # Modification logique pure
cmake . && make tank-module # Build autonome (5 secondes)
./build/tank-module        # Test standalone

# 3. Hot-reload dans jeu principal
# Engine détecte changement → Reload automatique → Game continue

Parallel Development

# Instance Claude A - Tank Logic
cd modules/tank/
# Context: 200 lignes tank behavior

# Instance Claude B - Economy Logic
cd modules/economy/
# Context: 250 lignes market simulation

# Instance Claude C - Factory Logic
cd modules/factory/
# Context: 300 lignes production optimization

# Zero conflicts, parallel commits, modular architecture

Évolution Progressive

Phase 1 : Prototype (Debug)

DebugEngine + SequentialModuleSystem + IntraIO
→ Développement ultra-rapide, Claude Code 100% focus logique
→ Step-by-step debugging, verbose logging
→ Validation concepts sans complexité infrastructure

Phase 2 : Optimization (Threading)

DebugEngine + ThreadedModuleSystem + IntraIO
→ Performance boost sans changer 1 ligne de game logic
→ Chaque module dans son thread dédié
→ Parallélisation automatique

Phase 3 : Production (High Performance)

HighPerfEngine + MultithreadedModuleSystem + LocalIO
→ Scale transparent, modules inchangés
→ Pool de threads optimisé
→ Communication inter-processus

Phase 4 : Scale Massive (Distribution)

DataOrientedEngine + ClusterModuleSystem + NetworkIO
→ Distribution multi-serveurs
→ SIMD optimization automatique
→ Claude Code développe toujours modules 200 lignes

Avantages Architecture

Pour Claude Code

• Micro-contexts : 200-300 lignes vs 50K+ lignes
• Focus logique : Zéro infrastructure, pure game logic
• Iteration speed : 5 secondes vs 5-10 minutes
• Parallel development : 3+ instances simultanées
• Hot-reload : Feedback instantané

Pour Performance

• Modular scaling : Chaque module à sa fréquence optimale
• Resource allocation : CPU budget précis par module
• Evolution path : Debug → Production sans réécriture
• Network tolerance : Latence adaptée par module type

Pour Maintenance

• Isolation complète : Failures localisées
• Testing granular : Chaque module testable indépendamment
• Code reuse : Modules réutilisables entre projets
• Documentation focused : Chaque module auto-documenté

Implementation Roadmap

Étape 1 : Core Infrastructure

• Implémenter IEngine, IModuleSystem, IModule, IIO interfaces
• DebugEngine + SequentialModuleSystem + IntraIO
• Module loader avec hot-reload basique

Étape 2 : Premier Module

• TankModule.cpp (200 lignes)
• Test standalone
• Intégration avec core

Étape 3 : Modules Core

• EconomyModule, FactoryModule, LogisticModule
• Communication JSON entre modules
• State preservation

Étape 4 : Performance

• ThreadedModuleSystem
• Optimisation hot-reload
• Métriques performance

Cette architecture révolutionnaire permet de développer des jeux AAA complexes avec Claude Code en utilisant des micro-contextes de 200 lignes, tout en conservant la puissance architecturale nécessaire pour des systèmes distribués massifs.