# CELUNA - Vue d'Ensemble du Projet

## Description

CELUNA est un assistant personnel intelligent conçu pour :
- Gérer le temps et l'hyperfocus (sessions max 2h)
- Faciliter l'apprentissage de langues
- Fournir des interventions proactives via IA pour forcer les transitions et planifier intelligemment

## Fonctionnalités MVP

### 1. SchedulerModule
- Planning de tâches
- Détection d'hyperfocus (maximum 2h)
- Rappels de pauses automatiques

### 2. AIAssistantModule
- Interventions contextuelles via Claude API
- Dialogue naturel
- Suggestions intelligentes basées sur le contexte

### 3. LanguageLearningModule
- Conversations dans la langue cible
- Corrections intelligentes en temps réel
- Adaptation au niveau de l'utilisateur

### 4. NotificationModule
- Alertes système Windows (toasts)
- Text-to-Speech (TTS)
- Support multilingue

### 5. DataModule
- Base de données SQLite locale
- Historique des sessions
- Métriques et statistiques d'utilisation

## Architecture Technique

### Principe Fondamental : Architecture Modulaire WarFactory

L'architecture s'inspire de GroveEngine et suit le principe WarFactory :
- **Hot-reload** : 0.4ms de latence de rechargement
- **Modules ultra-compacts** : 200-300 lignes maximum
- **Build autonome** : Chaque module se compile indépendamment

### Hiérarchie du Système

```
MainServer Process
├── CoordinationModule
│   └── Charge appconfig.json
├── DebugEngine
│   └── SequentialModuleSystem
└── Modules (.dll)
    ├── scheduler.dll
    ├── ai-assistant.dll
    ├── language.dll
    ├── notification.dll
    └── data.dll
```

### Les 5 Interfaces Fondamentales

```cpp
ICoordinationModule  // Orchestrateur global du système
    ↓
IEngine             // DebugEngine → HighPerfEngine (évolution)
    ↓
IModuleSystem       // Sequential → Threaded → Cluster (évolution)
    ↓
IModule             // Logique métier pure (200 lignes max)
    ↓
IIO                 // IntraIO → LocalIO → NetworkIO (évolution)
```

## Contraintes Architecturales CRITIQUES

### Règles pour les Modules

**Caractéristiques obligatoires** :
- ✅ 200-300 lignes maximum par module
- ✅ Logique métier pure (pas de threading, pas de network)
- ✅ Communication JSON uniquement entre modules
- ✅ Build autonome : `cmake .` depuis le répertoire du module

**Interdictions strictes** :
- ❌ `cmake ..` ou `#include "../"` (pas de dépendances parent)
- ❌ Modules dépassant 300 lignes
- ❌ Dépendances directes entre modules

**Principes de design** :
- ✅ Build autonome garanti
- ✅ Communication JSON standardisée
- ✅ Hot-reload ready (rechargement à chaud)
- ✅ Task-centric design (orienté tâches)

### Workflow de Développement

```bash
# Développement d'un module
cd modules/scheduler/
cmake .                  # JAMAIS cmake ..
make
./scheduler-test

# Edit SchedulerModule.cpp → Save → Hot-reload automatique en 0.4ms
```

## Communication Inter-Modules

### Format JSON Standardisé

Tous les modules communiquent exclusivement via messages JSON :

```json
// Détection d'hyperfocus → AIAssistantModule
{
  "event": "hyperfocus",
  "duration_minutes": 120
}

// AIAssistantModule → NotificationModule
{
  "type": "break_suggestion",
  "message": "Pause ?"
}

// NotificationModule → Système
{
  "notification": "system_toast",
  "tts": true
}
```

## Structure du Projet

```
Celuna/
├── CLAUDE.md                            # Instructions développement (obsolète → ce fichier)
├── docs/                                # Documentation technique
│   ├── README.md                        # Vue d'ensemble
│   ├── project-overview.md              # Ce fichier
│   ├── architecture/
│   │   ├── architecture-technique.md    # Architecture complète
│   │   └── intelligent-document-retrieval.md
│   └── GROVEENGINE_GUIDE.md             # Référence GroveEngine
├── modules/                             # Modules applicatifs (à créer)
│   ├── scheduler/
│   ├── ai-assistant/
│   ├── language-learning/
│   ├── notification/
│   └── data/
├── src/                                 # Infrastructure de base
├── config/                              # Configuration
├── external/                            # Dépendances tierces
└── build/                               # Artefacts de compilation
```

## Priorités de Développement

### Phase 1 : Infrastructure (EN COURS)
1. Créer les 5 interfaces fondamentales (IModule, IEngine, IModuleSystem, ICoordinationModule, IIO)
2. Implémenter le système de hot-reload
3. Mettre en place la communication JSON inter-modules

### Phase 2 : Modules Core
4. **SchedulerModule** (détection hyperfocus, planning)
5. **NotificationModule** (alertes Windows, TTS)

### Phase 3 : Modules IA
6. **AIAssistantModule** (intégration Claude API)
7. **LanguageLearningModule** (conversations, corrections)

### Phase 4 : Persistance
8. **DataModule** (SQLite, historique, métriques)

## Références Techniques

- **docs/README.md** : Vue d'ensemble générale du projet
- **docs/architecture/architecture-technique.md** : Spécifications architecturales détaillées
- **CDCDraft.md** : Cahier des charges complet
- **GroveEngine** : Architecture source WarFactory (accès via `.claude/settings.json`)

## Notes de Migration

Ce fichier remplace `CLAUDE.md` comme référence principale du projet. Le fichier `CLAUDE.md` sera renommé en `CLAUDE.md.old` pour archivage.
