couple-repo/Projects/WIP/GroveEngine.md

GroveEngine - Framework C++ Modulaire

Vue d'ensemble

Extraction et évolution du moteur modulaire de WarFactory en framework C++ indépendant et réutilisable avec hot-reload 0.4ms validé.

Objectif

Créer un framework C++ générique pour applications modulaires avec:

• Hot-reload DLL/SO ultra-rapide (0.4ms)
• Architecture propre par interfaces
• Types stricts C++
• Réutilisable pour multiples projets (AISSIA, WarFactory, futurs projets)

---

Origine

Extraction depuis WarFactory (27 octobre 2025)

Timeline

Date	Event	Détails
20 Sept	Architecture modulaire créée	Suppression engines monolithiques
24 Sept (fc28009)	Hot-reload validé 0.4ms	DebugEngine + IntraIO fonctionnels
27 Sept (f6c3b34)	IDataTree ajouté	Breaking change API → Impls supprimées
27 Oct 2025	Extraction GroveEngine	Création repo indépendant

Ce qui a été extrait

Headers (27 fichiers) :

include/grove/
├── Core interfaces
│   ├── IEngine.h
│   ├── IModule.h
│   ├── IModuleSystem.h
│   ├── IIO.h
│   └── ICoordinationModule.h, ITaskScheduler.h
├── Config system
│   ├── IDataTree.h
│   ├── IDataNode.h
│   └── DataTreeFactory.h
├── Communication
│   ├── IntraIO.h
│   ├── IntraIOManager.h
│   └── IOFactory.h
├── Factories
│   ├── EngineFactory.h
│   ├── ModuleFactory.h
│   └── ModuleSystemFactory.h
├── UI
│   ├── IUI.h
│   ├── IUI_Enums.h
│   └── ImGuiUI.h
└── Utilities
    ├── ISerializable.h
    ├── Resource.h
    ├── RandomGenerator.h
    └── ...

Implémentations (10 fichiers) - Récupérés depuis Git history :

src/
├── DebugEngine.cpp             (commit fc28009)
├── SequentialModuleSystem.cpp  (commit fc28009)
├── IntraIO.cpp                 (commit fb49fb2)
├── IntraIOManager.cpp          (commit fb49fb2)
├── IOFactory.cpp               (commit fb49fb2)
├── ModuleFactory.cpp           (commit fc28009)
├── EngineFactory.cpp           (commit fc28009)
├── ModuleSystemFactory.cpp     (commit fc28009)
├── ImGuiUI.cpp                 (déjà présent)
└── ResourceRegistry.cpp        (déjà présent)

Documentation :

• docs/architecture-modulaire.md : Explication interfaces
• docs/claude-code-integration.md : Workflow développement
• docs/CLAUDE-HOT-RELOAD-GUIDE.md : Guide hot-reload 0.4ms
• README.md : Guide complet framework

---

Architecture

Concepts Clés

1. IEngine : Moteur principal

• Gère lifecycle application
• Coordonne modules
• Gère boucle principale

2. IModule : Unité fonctionnelle

• ~200-300 lignes chacun
• Interface uniforme : initialize(), update(), shutdown()
• Hot-reload via DLL/SO

3. IIO : Communication inter-modules

• Messages typés
• Couplage faible
• IntraIO = implémentation locale

4. IModuleSystem : Orchestration

• Charge/décharge modules
• Gère dépendances
• SequentialModuleSystem = implémentation linéaire

5. IDataTree : Configuration

• Structure hiérarchique
• Type-safe
• Sérialisable JSON

Architecture Modulaire

┌─────────────────────────────────────────┐
│  Application (ex: aissia-core.exe)      │
│  ├─ main()                              │
│  └─ EngineFactory::create()            │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  IEngine (DebugEngine)                  │
│  ├─ IModuleSystem                       │
│  ├─ IIO (IntraIOManager)                │
│  └─ Game loop                           │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Modules (DLL/SO hot-reloadable)        │
│  ├─ module_a.dll (IModule)              │
│  ├─ module_b.dll (IModule)              │
│  └─ module_c.dll (IModule)              │
│      │                                   │
│      └─ update() appelé chaque frame    │
└─────────────────────────────────────────┘

Hot-Reload 0.4ms

Mécanisme validé (WarFactory, 24 Sept fc28009) :

// 1. Détection changement fichier DLL
if (filesystem::last_write_time("module.dll") > last_load_time) {
    // 2. Shutdown module actuel
    module->shutdown();

    // 3. Unload DLL
    FreeLibrary(dll_handle);

    // 4. Reload nouvelle DLL
    dll_handle = LoadLibrary("module.dll");

    // 5. Initialize nouveau module
    module->initialize(config, io);

    // Total: 0.4ms mesuré
}

Avantages :

• Modification code module → Recompile → Hot-reload automatique
• Pas de restart application
• State préservé (via sérialisation ISerializable)
• Itération ultra-rapide

---

Roadmap Développement

Phase 1 - MVP Standalone (Court terme)

Objectif : GroveEngine compile et fonctionne pour AISSIA

Tasks :

• Build test : Vérifier compilation complète
• Fix dépendances : nlohmann_json, ImGui
• Créer exemple "Hello World Module"
• Valider hot-reload 0.4ms avec exemple
• Documentation usage basique

Livrables :

• libGroveEngine.a (static lib) ou GroveEngine.dll (dynamic lib)
• Exemple compilable
• Guide "Créer premier module"

Bloquants :

• ⚠️ API mismatch IDataTree (impls utilisent json, interfaces utilisent IDataNode)
• Options :
  • A) Utiliser impls telles quelles (ignorer IDataTree pour MVP)
  • B) Adapter impls pour IDataTree
  • C) Wrapper temporaire json ↔ IDataNode

Phase 2 - Package System (Moyen terme)

Objectif : GroveEngine installable comme library externe

Tasks :

• CMake install targets
• Pkg-config / CMake find_package support
• Versioning sémantique (v0.1.0)
• Header-only option (alternative static/dynamic lib)
• vcpkg/conan packages (optionnel)

Livrables :

• Installation standard : cmake --install
• Utilisation externe :

  find_package(GroveEngine REQUIRED)
  target_link_libraries(my_app GroveEngine::GroveEngine)
  

Phase 3 - Framework Complet (Long terme)

Objectif : Framework mature, évolutif, documenté

Features :

• Tests automatisés (Google Test)
• CI/CD (GitHub Actions / Bitbucket Pipelines)
• Benchmarks performance
• Profiling tools intégrés
• Modules types additionnels :
  • NetworkModule (sockets, HTTP client)
  • DatabaseModule (SQLite, PostgreSQL)
  • AudioModule (OpenAL)
  • PhysicsModule (intégration Bullet/Box2D)
• Cross-platform validé :
  • Windows (MSVC, MinGW)
  • Linux (GCC, Clang)
  • macOS (Clang)
  • WebAssembly (Emscripten)
• Documentation complète :
  • API reference (Doxygen)
  • Tutorials
  • Architecture deep-dive
  • Best practices

Livrables :

• GroveEngine v1.0.0 stable
• Site documentation (GitHub Pages / ReadTheDocs)
• Exemples multiples (todo app, game, server, etc.)

Phase 4 - Écosystème (Très long terme)

Objectif : Framework communautaire (si open-source)

Features :

• Plugin marketplace
• Module templates generator
• Visual module editor (optionnel)
• Performance profiler UI
• Community contributions

---

Problèmes Techniques Identifiés

1. API Mismatch IDataTree

Situation :

// Ancienne API (implémentations actuelles)
void initialize(const nlohmann::json& config, IIO* io);

// Nouvelle API (interfaces actuelles)
void setConfiguration(const IDataNode& config, IIO* io);

Impact :

• DebugEngine.cpp, IntraIO.cpp, etc. = incompatibles avec IDataTree
• Besoin adaptation ou wrapper

Solutions :

Option	Effort	Risk	Délai
A) Ignorer IDataTree	Faible	Moyen	Immédiat
B) Adapter impls	Moyen	Faible	2-3 jours
C) Wrapper json↔IDataNode	Faible	Moyen	1 jour

Recommandation : Option A pour MVP AISSIA, Option B pour Phase 2

2. Dépendances Externes

Actuelles :

• nlohmann_json : Configuration (FetchContent CMake)
• ImGui : UI (FetchContent CMake)
• OpenGL/GLFW : ImGui backend (système)

Problèmes potentiels :

• ImGui/OpenGL requis même si pas d'UI (fix : optional dependency)
• Version conflicts si projet utilise déjà nlohmann_json

Solutions :

• CMake options : GROVEENGINE_BUILD_UI, GROVEENGINE_USE_SYSTEM_JSON
• Header-only mode sans dépendances lourdes

3. Cross-Platform Hot-Reload

Windows : LoadLibrary / FreeLibrary ✅ Validé Linux : dlopen / dlclose ⏳ Non testé macOS : dlopen / dlclose ⏳ Non testé WASM : Pas de hot-reload natif ⚠️ Besoin architecture différente

Solutions :

• Abstraction plateforme : IPlatformLoader interface
• WASM : Pre-load tous modules, switch callbacks (pas vrai hot-reload)

4. State Preservation

Problème : Hot-reload = nouveau module, state perdu

Solution actuelle :

class IModule {
    virtual void serialize(IDataNode& out) = 0;
    virtual void deserialize(const IDataNode& in) = 0;
};

// Avant reload
old_module->serialize(state);

// Après reload
new_module->deserialize(state);

Limitation : Pointeurs invalides après reload Fix : ID-based references, pas de raw pointers entre modules

---

Relation avec Autres Projets

Projets Utilisateurs

1. AISSIA (Projet 3)

   • Premier utilisateur de GroveEngine
   • Modules : Monitoring, Scheduler, AI, Notifications, UI
   • Dépend de Phase 1 GroveEngine

2. WarFactory (futur)

   • Source originale de GroveEngine
   • Long terme : Remplacer son core par GroveEngine packagé
   • Modules : Rendering, Physics, AI, Audio, Network

3. Futurs projets

   • Serveur backend modulaire
   • Tools/Utilities avec UI
   • Prototypes rapides

Dépendances

GroveEngine (Projet 4)
    ↓ utilisé par
AISSIA (Projet 3)
    ↓ utilise aussi
Social Network Manager (Projet 1) - si implémenté en C++
MP3→TXT (Projet 2) - standalone Python

---

Décisions Stratégiques en Attente

Open-Source

Question : Rendre GroveEngine public ?

Option	Avantages	Inconvénients
Open-source (MIT/Apache)	Communauté, portfolio, contributions	Maintenance, support users
Private (Bitbucket)	Contrôle total, pas de support	Pas de contributions externes

Impact : Si public → besoin CI/CD, doc complète, issue tracking

Versioning

Question : Stratégie releases ?

• Semantic versioning : v0.1.0 (MVP) → v0.2.0 (features) → v1.0.0 (stable)
• Date-based : 2025.10, 2025.11, etc.
• Rolling : Pas de versions, juste main branch

Recommandation : Semantic versioning pour clarté

Priorité vs AISSIA

Question : Développer GroveEngine en parallèle ou bloquer AISSIA ?

Approche	Pros	Cons
Séquentiel : Finir GroveEngine MVP → Démarrer AISSIA	GroveEngine propre dès le début	AISSIA retardé 1-2 semaines
Parallèle : Utiliser GroveEngine "as-is", améliorer en même temps	AISSIA démarre immédiatement	Potentiel refactoring lourd plus tard

Recommandation : Parallèle avec GroveEngine Phase 1 quick (2-3 jours max)

---

Estimation Effort

Phase 1 - MVP (Court terme)

Durée : 2-5 jours

• Build fix + tests : 1 jour
• Hello World exemple : 1 jour
• Documentation usage : 1 jour
• Buffer bugs : 1-2 jours

Phase 2 - Package System (Moyen terme)

Durée : 1-2 semaines

• CMake install : 2 jours
• Versioning : 1 jour
• Pkg-config/find_package : 2 jours
• Testing intégration : 3 jours

Phase 3 - Framework Complet (Long terme)

Durée : 2-6 mois

• Tests automatisés : 2 semaines
• CI/CD : 1 semaine
• Cross-platform validation : 3 semaines
• Modules additionnels : 4-8 semaines
• Documentation complète : 4 semaines

Phase 4 - Écosystème (Très long terme)

Durée : 6+ mois continu

• Dépend de l'adoption
• Communauté-driven

---

Risques

Risque	Probabilité	Impact	Mitigation
API instable	Moyenne	Élevé	Versioning strict, deprecation policy
Hot-reload bugs cross-platform	Moyenne	Moyen	Tests automatisés par plateforme
Complexité trop élevée	Faible	Élevé	Garder core simple, features = opt-in
Maintenance long terme	Élevée	Moyen	Documentation exhaustive, tests
Over-engineering	Élevée	Moyen	Focus MVP d'abord, features après

---

Statut Actuel

Repo

• ✅ Créé : Projets/GroveEngine/
• ✅ Structure complète (headers + impls + docs + CMake)
• ⏳ Build jamais testé
• ⏳ Hot-reload pas revalidé depuis extraction

Code

• ✅ 27 headers
• ✅ 10 implémentations (.cpp)
• ⚠️ API mismatch IDataTree
• ⏳ Exemples manquants

Documentation

• ✅ Architecture modulaire expliquée
• ✅ Guide hot-reload
• ⏳ Guide "Créer premier projet avec GroveEngine" manquant

Tests

• ❌ Aucun test automatisé
• ❌ CI/CD pas configuré
• ✅ Hot-reload 0.4ms validé historiquement (WarFactory fc28009)

---

Prochaines Étapes Recommandées

Immédiat (Avant AISSIA)

1. Build test GroveEngine standalone
2. Fix erreurs compilation si présentes
3. Créer examples/hello_module/ minimal
4. Valider hot-reload fonctionne toujours
5. Doc "Quick Start" pour AISSIA

Court terme (Parallèle AISSIA)

1. Fixer API mismatch IDataTree (option A ou B)
2. CMake install targets basiques
3. Versioning v0.1.0-alpha

Moyen terme (Post-MVP AISSIA)

1. Tests automatisés
2. CI/CD basique
3. Documentation API complète
4. Cross-platform Linux validation

Long terme (Évolution continue)

1. Modules additionnels (Network, Database, etc.)
2. Performance optimizations
3. Communauté (si open-source)

---

Ressources

Repos

• GroveEngine : Projets/GroveEngine/
• Source (WarFactory) : Projets/warfactoryracine/
• Premier utilisateur : Projets/aissia/

Documentation

• GroveEngine/docs/architecture-modulaire.md
• GroveEngine/docs/claude-code-integration.md
• GroveEngine/docs/CLAUDE-HOT-RELOAD-GUIDE.md
• GroveEngine/README.md

Commits Git Importants (WarFactory)

• fc28009 : Hot-reload 0.4ms validé + DebugEngine fonctionnel
• fb49fb2 : IntraIO implementation
• f6c3b34 : IDataTree ajouté (breaking change)

---

Créé : 27 octobre 2025 Statut : Extrait, non testé - Développement long terme Stack : C++17, CMake, nlohmann_json, ImGui Performance : Hot-reload 0.4ms validé (à revalider)