# CELUNA Documentation

**CELUNA** (AI Smart Schedule & Interactive Assistant) - Assistant personnel intelligent pour la gestion du temps et de l'hyperfocus.

## Vue d'Ensemble

CELUNA est un assistant personnel proactif qui aide à gérer le temps, les priorités et l'hyperfocus en utilisant l'architecture modulaire WarFactory pour un développement rapide avec hot-reload.

### Problème Résolu

- **Hyperfocus** : Incapacité à stopper une tâche une fois démarrée
- **Absence de limites** : Continuer jusqu'à épuisement physique
- **Transitions difficiles** : Difficulté à passer d'une activité à une autre
- **Régulation défaillante** : Besoin d'un système externe pour gérer l'attention

### Solution Proposée

Assistant intelligent qui :
- Intervient de manière proactive selon planning
- Planifie intelligemment avec l'IA
- Force les transitions quand nécessaire
- S'adapte aux besoins utilisateur
- Accompagne l'apprentissage de langues étrangères

## Architecture

CELUNA réutilise l'**architecture modulaire WarFactory** :

- **Hot-reload 0.4ms** : Modifications instantanées sans restart
- **Modules 200-300 lignes** : Développement optimisé pour Claude Code
- **Build autonome** : `cmake .` depuis chaque module
- **Développement parallèle** : Multiple instances Claude Code simultanées

### Avantages Clés

✅ **Développement ultra-rapide** : Hot-reload validé à 0.4ms
✅ **Types stricts C++** : Pas de "wildcode"
✅ **Architecture éprouvée** : WarFactory validé en production
✅ **Privacy-first** : Mode local, données jamais uploadées
✅ **Évolution progressive** : MVP → Production → Cloud sans réécriture

## Structure Documentation

```
docs/
├── README.md                          # Ce fichier
├── architecture/                      # Architecture technique
│   ├── architecture-modulaire.md      # Interfaces WarFactory (IEngine, IModule, IIO)
│   ├── architecture-technique.md      # Architecture système complète
│   ├── claude-code-integration.md     # Intégration Claude Code
│   └── intelligent-document-retrieval.md  # Retrieval agentique pour AIAssistantModule
└── implementation/                    # Guides d'implémentation
    ├── CLAUDE-HOT-RELOAD-GUIDE.md    # Guide hot-reload (0.4ms)
    ├── AUTOMATION_GUIDE.md           # Automatisation du build
    ├── ADVANCED_TESTING.md           # Stratégies de test
    └── configuration/                # Configuration système
        ├── module-configuration.md
        ├── deployment-strategies.md
        ├── error-handling.md
        ├── module-versioning.md
        └── security-measures.md
```

## Démarrage Rapide

### 1. Lire l'Architecture

**Ordre recommandé :**

1. **[architecture-modulaire.md](architecture/architecture-modulaire.md)**
   → Comprendre les 5 interfaces fondamentales (IEngine, IModule, IModuleSystem, IIO, ICoordinationModule)

2. **[architecture-technique.md](architecture/architecture-technique.md)**
   → Voir comment CELUNA utilise WarFactory pour ses modules

3. **[intelligent-document-retrieval.md](architecture/intelligent-document-retrieval.md)**
   → Architecture retrieval agentique pour AIAssistantModule (gestion documents, context window)

4. **[CLAUDE-HOT-RELOAD-GUIDE.md](implementation/CLAUDE-HOT-RELOAD-GUIDE.md)**
   → Workflow de développement avec hot-reload 0.4ms

### 2. Modules CELUNA Prévus

**MVP Phase 1 (Local uniquement) :**
- `SchedulerModule` : Planning intelligent des tâches
- `AIAssistantModule` : Interventions contextuelles via LLM
- `NotificationModule` : Alertes et TTS
- `DataModule` : Persistance SQLite
- `LanguageLearningModule` : Apprentissage et pratique de langues étrangères

**Phase 2+ (Optionnel Cloud) :**
- Distribution modules IA sur serveur
- Synchronisation multi-appareils
- Mode PWA installable

### 3. Workflow Développement

```bash
# Développement d'un module (exemple : SchedulerModule)
cd modules/scheduler/
code CLAUDE.md              # Lire les instructions spécifiques
cmake . && make             # Build autonome
./scheduler-test            # Tests standalone

# Edit SchedulerModule.cpp → Save
# → Auto-rebuild + hot-reload < 0.4ms !
```

## Philosophie de Développement

### MVP-First

- **Phase 1 obligatoire** : Mode local Windows uniquement
- **Phases 2-4 optionnelles** : Seulement si besoin validé
- **Configuration-driven** : 90% des besoins via JSON
- **Simplicité d'abord** : Complexité émerge de l'interaction

### Développement Parallèle

```bash
# Instance Claude Code A
cd modules/scheduler/
# Context: 280 lignes (CLAUDE.md + Module.cpp + IModule.h)

# Instance Claude Code B
cd modules/ai-assistant/
# Context: 250 lignes

# Instance Claude Code C
cd modules/language-learning/
# Context: 230 lignes
```

### Évolution Progressive

```cpp
// Phase 1 : MVP (obligatoire)
DebugEngine + SequentialModuleSystem + IntraIO
→ Développement ultra-rapide, hot-reload 0.4ms

// Phase 2 : Optimization (optionnel)
DebugEngine + ThreadedModuleSystem + IntraIO
→ Performance sans réécriture

// Phase 3 : Production (optionnel)
HighPerfEngine + MultithreadedModuleSystem + LocalIO
→ Scale transparent

// Phase 4 : Cloud (optionnel)
DataOrientedEngine + ClusterModuleSystem + NetworkIO
→ Distribution massive
```

## Cahiers des Charges

**Documents principaux à la racine :**

- **[CDCDraft.md](../CDCDraft.md)** : Cahier des charges complet CELUNA
- **[AlternativesAnalysis.md](../AlternativesAnalysis.md)** : Analyse comparative des options techniques

## Liens Externes

- **WarFactory Engine** : Architecture source utilisée par CELUNA
- **Claude Code** : https://docs.claude.com/en/docs/claude-code

## Contribution

Ce projet utilise une approche de développement modulaire optimisée pour Claude Code. Chaque module est autonome et peut être développé indépendamment.

**Contraintes strictes :**
- ✅ Modules 200-300 lignes maximum
- ✅ Build autonome : `cmake .` depuis le module
- ✅ JSON-only communication
- ✅ Zero dependencies up
- ❌ Jamais `cmake ..` ou `#include "../"`

## Licence

À définir
