couple-repo/Projects/WIP/ProjectOrganizer.md

ProjectOrganizer - GroveEngine Module

Vue d'ensemble

Module GroveEngine C++ pour analyse, classification et organisation automatique de dossiers de projets avec génération de visualisations et rapports.

Objectif

Créer un module GroveEngine qui :

• Analyse récursivement un dossier projet
• Classifie et organise tous les documents
• Détecte et mappe les relations entre fichiers
• Génère des visualisations (graphes de dépendances)
• Produit des outputs structurés (JSON, Markdown, HTML)

---

Spécifications Techniques

Intégration GroveEngine

Type : IModule (DLL/SO hot-reloadable)

Communication : Via IIO (IntraIO)

Architecture :

Application
    ↓
GroveEngine (IEngine)
    ↓
ProjectOrganizerModule (IModule)
    ├─ Reçoit requêtes via IIO
    ├─ Analyse filesystem
    ├─ Classifie/organise
    ├─ Génère outputs
    └─ Retourne résultats via IIO

API IIO

Input messages :

{
  "action": "analyze",
  "source_path": "/path/to/project",
  "output_path": "/path/to/results",
  "options": {
    "use_llm": false,
    "file_types": ["txt", "md", "pdf", "doc", "docx", "ppt", "pptx"],
    "max_depth": -1,
    "generate_graphs": true,
    "copy_source": true
  }
}

Output messages :

{
  "status": "success",
  "output_path": "/path/to/results",
  "stats": {
    "files_processed": 142,
    "files_classified": 138,
    "relations_found": 67,
    "duration_ms": 1243
  },
  "summary": {
    "categories": {
      "documentation": 45,
      "code": 23,
      "config": 12,
      "data": 58
    }
  }
}

---

Fonctionnalités

Phase 1 - MVP Sans LLM (Court terme)

Formats supportés : .txt, .md

Capacités :

• Copie récursive du dossier source
• Scan tous fichiers txt/md
• Classification basique par :
  • Extension de fichier
  • Localisation (dossier parent)
  • Patterns dans nom fichier
• Détection relations :
  • Liens markdown [text](file.md)
  • Références explicites chemin fichier
  • Mentions de noms de fichiers
• Génération outputs :
  • JSON : Structure complète + métadonnées
  • Markdown : Rapport lisible + index
  • HTML : Visualisation interactive

Graphes générés :

• Graph de dépendances (qui référence qui)
• Graph de catégories (regroupement thématique)
• Graph de structure (arborescence dossiers)

Livrables :

output/
├── organized/           # Copie organisée du projet
│   ├── documentation/
│   ├── code/
│   ├── config/
│   └── data/
├── analysis/
│   ├── structure.json   # Données brutes
│   ├── relations.json   # Graphe de relations
│   ├── report.md        # Rapport markdown
│   └── index.html       # Visualisation interactive
└── graphs/
    ├── dependencies.svg
    ├── categories.svg
    └── structure.svg

Durée estimée : 1-2 semaines

Phase 2 - Formats Avancés (Moyen terme)

Nouveaux formats : .pdf (OCR), .doc, .docx, .ppt, .pptx

Capacités additionnelles :

• Extraction texte PDF avec OCR (Tesseract/PaddleOCR)
• Parsing Office documents (LibreOffice SDK / Apache POI via JNI)
• Détection langage automatique
• Extraction métadonnées (auteur, date, tags)

Durée estimée : 2-3 semaines

Phase 3 - Analyse LLM (Long terme)

Intégration LLM : Via IIO vers module LLM externe

Capacités LLM :

• Classification sémantique profonde
• Détection relations implicites
• Extraction concepts clés
• Génération résumés
• Suggestions réorganisation

Architecture :

ProjectOrganizerModule
    ↓ (IIO message)
LLMModule (Claude/GPT via API)
    ↓ (response)
ProjectOrganizerModule

Durée estimée : 3-4 semaines

Phase 4 - Analyse Code (Très long terme)

Langages supportés : C++, Python, JavaScript, Java, etc.

Capacités :

• Parsing AST (Abstract Syntax Tree)
• Détection dépendances imports
• Call graph génération
• Détection fonctions inutilisées
• Analyse complexité

Outils :

• Clang LibTooling (C++)
• Tree-sitter (multi-langage)
• LSP integration possible

Note : Pas prioritaire, code n'est pas la target principale

Durée estimée : 4-6 semaines

---

Workflows Typiques

Workflow 1 : Analyse Projet Existant

// 1. User lance via IIO
io->send("ProjectOrganizer", {
  "action": "analyze",
  "source_path": "E:/Projets/MyProject",
  "output_path": "E:/Projets/MyProject_Analysis"
});

// 2. Module process
// - Copie récursive
// - Scan fichiers
// - Classification
// - Détection relations
// - Génération outputs

// 3. Module répond
io->receive([](const Message& msg) {
  if (msg.status == "success") {
    // Ouvrir index.html
    system("start E:/Projets/MyProject_Analysis/analysis/index.html");
  }
});

Workflow 2 : Watch Mode (Future)

// Mode surveillance continue
io->send("ProjectOrganizer", {
  "action": "watch",
  "source_path": "E:/Projets/MyProject",
  "update_interval_ms": 5000
});

// Module update analysis automatiquement toutes les 5s

---

Architecture Interne Module

Classes Principales

// Module principal
class ProjectOrganizerModule : public IModule {
public:
    void initialize(const IDataNode& config, IIO* io) override;
    void update(float deltaTime) override;
    void shutdown() override;

private:
    FileScanner scanner_;
    Classifier classifier_;
    RelationDetector relationDetector_;
    OutputGenerator outputGenerator_;
};

// Scanner filesystem
class FileScanner {
public:
    std::vector<FileInfo> scanRecursive(const std::string& path);
};

// Classification fichiers
class Classifier {
public:
    Category classify(const FileInfo& file);
};

// Détection relations
class RelationDetector {
public:
    std::vector<Relation> detect(const std::vector<FileInfo>& files);
};

// Génération outputs
class OutputGenerator {
public:
    void generateJSON(const Analysis& analysis, const std::string& path);
    void generateMarkdown(const Analysis& analysis, const std::string& path);
    void generateHTML(const Analysis& analysis, const std::string& path);
    void generateGraphs(const Analysis& analysis, const std::string& path);
};

Structures de Données

struct FileInfo {
    std::string path;
    std::string name;
    std::string extension;
    size_t size;
    time_t modified;
    Category category;
    std::string content;  // Si text-based
};

enum class Category {
    Documentation,
    Code,
    Config,
    Data,
    Media,
    Archive,
    Unknown
};

struct Relation {
    std::string from;     // Fichier source
    std::string to;       // Fichier cible
    RelationType type;    // Link, Import, Reference
    std::string context;  // Ligne où trouvé
};

struct Analysis {
    std::vector<FileInfo> files;
    std::vector<Relation> relations;
    std::map<Category, int> stats;
    std::chrono::milliseconds duration;
};

---

Dépendances

Requises (Phase 1)

• C++17 : Filesystem API (<filesystem>)
• nlohmann_json : Génération JSON (déjà dans GroveEngine)
• Graphviz : Génération graphes SVG (external process call)

Optionnelles (Phases 2+)

• Tesseract/PaddleOCR : OCR pour PDFs
• LibreOffice SDK : Parsing Office documents
• Tree-sitter : Parsing code (Phase 4)

Note

Toutes les dépendances lourdes (LLM, OCR) via IIO vers modules externes, pas intégrées directement.

---

Génération Visualisations

Format Graphviz DOT

Example dependencies graph :

digraph dependencies {
    rankdir=LR;
    node [shape=box];

    "README.md" -> "docs/architecture.md";
    "README.md" -> "docs/setup.md";
    "src/main.cpp" -> "include/engine.h";
    "include/engine.h" -> "include/module.h";
}

Génération :

void OutputGenerator::generateGraphs(const Analysis& analysis, const std::string& path) {
    // 1. Créer fichier DOT
    std::ofstream dot(path + "/dependencies.dot");
    dot << "digraph dependencies {\n";
    for (const auto& rel : analysis.relations) {
        dot << "  \"" << rel.from << "\" -> \"" << rel.to << "\";\n";
    }
    dot << "}\n";
    dot.close();

    // 2. Appeler Graphviz
    system("dot -Tsvg dependencies.dot -o dependencies.svg");
}

Format HTML Interactif

Technologies :

• vis.js : Graphes interactifs
• D3.js : Alternative visualisations
• Bootstrap : UI propre

Features :

• Zoom/pan sur graphe
• Click fichier → Affiche infos
• Filtres par catégorie
• Search bar

---

Performance

Cibles

• Scan 1000 fichiers : < 1s
• Classification : < 100ms (sans LLM)
• Détection relations : < 500ms
• Génération outputs : < 2s

Optimisations

• Multi-threading scan filesystem
• Cache résultats (inotify/FileSystemWatcher pour détecter changements)
• Lazy loading contenu fichier (seulement si nécessaire)
• Streaming génération HTML (pas tout en RAM)

---

Configuration Module

Fichier config : config/project_organizer.json

{
  "default_output_path": "~/.groveengine/project_analysis",
  "file_types": {
    "phase1": ["txt", "md"],
    "phase2": ["pdf", "doc", "docx", "ppt", "pptx"],
    "phase4": ["cpp", "h", "py", "js", "java"]
  },
  "classification_rules": {
    "documentation": ["README", "docs/", ".md"],
    "code": ["src/", "include/", ".cpp", ".h"],
    "config": ["config/", ".json", ".yaml", ".toml"]
  },
  "graph_engine": "graphviz",
  "max_file_size_mb": 10,
  "use_cache": true
}

---

Tests

Tests Unitaires

TEST(FileScanner, ScanRecursive) {
    FileScanner scanner;
    auto files = scanner.scanRecursive("test_data/sample_project");
    EXPECT_GT(files.size(), 0);
}

TEST(Classifier, ClassifyMarkdown) {
    Classifier classifier;
    FileInfo file{"README.md", "README.md", "md", 1024, 0, Category::Unknown, ""};
    EXPECT_EQ(classifier.classify(file), Category::Documentation);
}

TEST(RelationDetector, DetectMarkdownLinks) {
    RelationDetector detector;
    FileInfo file{"test.md", "test.md", "md", 0, 0, Category::Unknown,
                  "See [other](other.md) for details"};
    auto relations = detector.detect({file});
    EXPECT_EQ(relations.size(), 1);
    EXPECT_EQ(relations[0].to, "other.md");
}

Tests Intégration

• Test projet réel (couple_matters repo)
• Validation outputs générés
• Performance benchmarks

---

Roadmap Développement

Phase 1 - MVP (1-2 semaines)

• Setup module GroveEngine boilerplate
• FileScanner implementation
• Classifier basique (extension + path)
• RelationDetector markdown links
• OutputGenerator JSON + MD
• Tests unitaires basiques
• Exemple fonctionnel

Phase 2 - Formats Avancés (2-3 semaines)

• Intégration OCR (PDF)
• Parser Office docs
• OutputGenerator HTML interactif
• Graph generation (Graphviz)
• Performance optimizations
• Tests intégration

Phase 3 - LLM (3-4 semaines)

• IIO protocol vers LLM module
• Classification sémantique
• Détection relations implicites
• Génération résumés
• A/B testing LLM vs non-LLM

Phase 4 - Code Analysis (4-6 semaines)

• Tree-sitter integration
• AST parsing multi-langage
• Call graph generation
• Unused code detection
• Complexity metrics

---

Problèmes Anticipés

1. Performance Gros Projets

Problème : Projet 10,000+ fichiers = scan lent

Solutions :

• Multi-threading (std::async)
• Filtrage intelligent (ignorer node_modules, .git)
• Incremental analysis (cache + watch mode)

2. Encodings Fichiers

Problème : Fichiers UTF-8, UTF-16, ISO-8859-1, etc.

Solutions :

• Auto-détection encoding (libiconv/ICU)
• Fallback UTF-8 + ignore errors
• Log fichiers non-parsables

3. Graphes Trop Complexes

Problème : 1000+ nodes = illisible

Solutions :

• Clustering par catégorie
• Zoom levels (overview → détail)
• Filtres interactifs HTML

4. Faux Positifs Relations

Problème : Détecte "test.md" dans commentaire comme lien

Solutions :

• Heuristiques strictes (markdown syntax only)
• LLM validation (Phase 3)
• Whitelist/blacklist user

---

Exemples Utilisation

Exemple 1 : Analyse couple_matters Repo

Input :

{
  "action": "analyze",
  "source_path": "E:/Users/Alexis Trouvé/Documents/Projets/couple_matters",
  "output_path": "E:/couple_matters_analysis"
}

Output attendu :

• 200+ fichiers markdown classifiés
• Relations détectées :
  • CLAUDE.md → ToRemember/schema.md
  • personnalités/Tingting.md → personnalités/TingtingWork.md
  • Projects/Status_Projets.md → tous les Projects/*/projet.md
• Graphe catégories :
  • Couple (50%)
  • Projets (30%)
  • Planning (10%)
  • Autres (10%)

Exemple 2 : Analyse Codebase C++

Input :

{
  "action": "analyze",
  "source_path": "E:/Projets/GroveEngine",
  "options": {
    "file_types": ["cpp", "h", "md"]
  }
}

Output attendu :

• Headers classifiés par module
• Includes graph
• Documentation liée au code

---

Risques

Risque	Probabilité	Impact	Mitigation
Over-engineering	Élevée	Moyen	MVP strict Phase 1, features après
Performance inacceptable gros projets	Moyenne	Élevé	Benchmarks early, optimizations prioritaires
OCR/Office parsing complexe	Moyenne	Moyen	Phase 2 optionnelle, focus txt/md d'abord
Graphviz dépendance externe	Faible	Faible	Fallback text-based graph si absent
Scope creep vers IDE	Élevée	Élevé	Focus analyse/organisation, pas édition

---

Statut Actuel

Code

• ❌ Aucun code écrit
• ❌ Module pas créé dans GroveEngine

Design

• ✅ Spécifications complètes
• ✅ API IIO définie
• ✅ Architecture interne définie

Tests

• ❌ Aucun test

Documentation

• ✅ Ce fichier (fiche projet)
• ⏳ Guide utilisateur à écrire

---

Prochaines Étapes

Immédiat

1. Créer GroveEngine/modules/ProjectOrganizer/ folder structure
2. Setup CMake pour module
3. Créer squelette ProjectOrganizerModule.cpp
4. Implement FileScanner basique
5. Test scan sur petit projet

Court terme

1. Classifier implementation
2. RelationDetector markdown
3. OutputGenerator JSON
4. Test sur couple_matters repo

Moyen terme

1. OutputGenerator Markdown + HTML
2. Graphviz integration
3. Performance optimization
4. Documentation utilisateur

---

Ressources

Repos

• GroveEngine : E:/Projets/GroveEngine/
• Module location : E:/Projets/GroveEngine/modules/ProjectOrganizer/
• Test data : E:/Users/Alexis Trouvé/Documents/Projets/couple_matters/

Documentation

• GroveEngine/docs/architecture-modulaire.md : Système IModule
• GroveEngine/docs/CLAUDE-HOT-RELOAD-GUIDE.md : Hot-reload workflow

External Tools

• Graphviz : https://graphviz.org/
• vis.js : https://visjs.org/
• PaddleOCR : https://github.com/PaddlePaddle/PaddleOCR (Phase 2)

---

Créé : 28 novembre 2025 Statut : CONCEPT → WIP (Phase 1) Stack : C++17, GroveEngine IModule, nlohmann_json, Graphviz Target : Analyse/organisation projets documentation-heavy