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

```cpp
// 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 :
  ```cmake
  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** :
```cpp
// 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** :
```cpp
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)*