StillHammer 9a883502bb Integrate client/server modulaire and distribution performance-based specifications

- Add Client/Server Modulaire architecture (Point 4) with V1/V2 progression and user/dev implications
- Add Distribution Performance-Based system (Point 5) with Critical/Strategic module classification
- Update CLAUDE.md to reflect modular architecture transition
- Consolidate documentation: move specialized docs to toCheck/ for systematic integration
- Remove obsolete architecture files replaced by integrated specifications

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-09-21 07:34:57 +08:00

17 KiB

Raw Blame History

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

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

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

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

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