StillHammer
7425f4af2e
## Projects Organization - Create status-based folders: WIP/PAUSE/CONSTANT/CONCEPT/ARCHIVE - Move 17 projects to appropriate status folders - Delete obsolete README.md ### WIP (4 projects) - GroveEngine, SEO_Article_Generator, AISSIA, SecondVoice ### PAUSE (6 projects) - Warfactory, chinese_audio_tts_pipeline, MCP_Game_Asset_Pipeline - ocr_pdf_service, Essay_Writing_Tingting, shipping_strategy/ ### CONSTANT (3 projects) - ClassGen (Analysis + 2.0), Database_Cours_Chinois, civjdr ### CONCEPT (5 projects) - pokrovsk_last_day, pokrovsk_drone_command (NEW full design doc) - social_network_manager, vps_tunnel_china, Claude_Workflow_Optimization ### ARCHIVE (3 items) - MCP_Creative_Amplification, Backlog_9-10_Octobre_2025, LeBonCoup/ ## Tracking Files Updated - Status_Projets.md: Complete rewrite with current state (Nov 2025) - planning/TODO_data.md: Updated with new structure and all projects by status - CLAUDE.md: Updated relation status, Projects section, daily check stats ## Daily Check System - Add card ACTION-008: essay_writing_tingting - Update card_database.md: 21 total cards (15 Tingting, 3 Personal, 1 Family, 1 Tech, 1 Comm) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
524 lines
15 KiB
Markdown
524 lines
15 KiB
Markdown
# 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)*
|