docs: Add GroveEngine documentation and project overview
- Add comprehensive README.md explaining Aissia is built on GroveEngine - Add GROVEENGINE_GUIDE.md with complete user guide - Add docs/project-overview.md - Archive old CLAUDE.md to CLAUDE.md.old 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
f6f4813d8f
commit
439b55b176
222
README.md
Normal file
222
README.md
Normal file
@ -0,0 +1,222 @@
|
|||||||
|
# AISSIA - AI Smart Schedule & Interactive Assistant
|
||||||
|
|
||||||
|
**AISSIA** is an intelligent personal assistant for time management, hyperfocus detection, and language learning, powered by **GroveEngine**.
|
||||||
|
|
||||||
|
## What is AISSIA?
|
||||||
|
|
||||||
|
AISSIA helps manage:
|
||||||
|
- **Hyperfocus**: Detects when you've been working too long and need a break
|
||||||
|
- **Time Management**: Intelligent scheduling and task planning
|
||||||
|
- **Language Learning**: Interactive practice in target languages
|
||||||
|
- **Notifications**: Context-aware alerts with TTS support
|
||||||
|
|
||||||
|
## Built on GroveEngine
|
||||||
|
|
||||||
|
AISSIA leverages **GroveEngine**, a C++17 hot-reload module system that enables:
|
||||||
|
|
||||||
|
- **Hot-Reload**: Modify code at runtime without losing state (<1ms reload latency)
|
||||||
|
- **Modular Architecture**: Self-contained modules (200-300 lines each)
|
||||||
|
- **Pub/Sub Communication**: Decoupled inter-module messaging
|
||||||
|
- **State Preservation**: Automatic state serialization across reloads
|
||||||
|
- **Configuration Hot-Reload**: Update settings without code changes
|
||||||
|
|
||||||
|
### Why GroveEngine?
|
||||||
|
|
||||||
|
✅ **Ultra-fast Development**: Hot-reload validated at 0.4ms
|
||||||
|
✅ **Type Safety**: Strong C++ typing, no "wildcode"
|
||||||
|
✅ **Proven Architecture**: Production-ready module system
|
||||||
|
✅ **Privacy-First**: Local mode, data never uploaded
|
||||||
|
✅ **Progressive Evolution**: MVP → Production → Cloud without rewrite
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Aissia/
|
||||||
|
├── external/
|
||||||
|
│ └── GroveEngine/ # GroveEngine (symlink)
|
||||||
|
├── src/
|
||||||
|
│ ├── main.cpp # Main application loop
|
||||||
|
│ └── modules/
|
||||||
|
│ ├── SchedulerModule.* # Time management & hyperfocus
|
||||||
|
│ ├── NotificationModule.* # Alerts & TTS
|
||||||
|
│ ├── AIAssistantModule.* # (TODO) LLM integration
|
||||||
|
│ ├── LanguageLearningModule.* # (TODO) Language practice
|
||||||
|
│ └── DataModule.* # (TODO) SQLite persistence
|
||||||
|
├── config/
|
||||||
|
│ ├── scheduler.json
|
||||||
|
│ └── notification.json
|
||||||
|
├── docs/
|
||||||
|
│ ├── README.md # Project documentation
|
||||||
|
│ └── GROVEENGINE_GUIDE.md # GroveEngine user guide
|
||||||
|
└── CMakeLists.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## Modules
|
||||||
|
|
||||||
|
### Implemented
|
||||||
|
|
||||||
|
**SchedulerModule**: Time management and hyperfocus detection
|
||||||
|
- Tracks work sessions and break intervals
|
||||||
|
- Detects hyperfocus based on configurable threshold (default: 120 minutes)
|
||||||
|
- Reminds for breaks (default: every 45 minutes)
|
||||||
|
- Task estimation and tracking
|
||||||
|
|
||||||
|
**NotificationModule**: System alerts with priority levels
|
||||||
|
- Priority-based notifications (LOW, NORMAL, HIGH, URGENT)
|
||||||
|
- Silent mode (respects URGENT priority)
|
||||||
|
- TTS support (configurable)
|
||||||
|
- Multilingual support (fr/en/jp)
|
||||||
|
- Queue management with rate limiting
|
||||||
|
|
||||||
|
### Planned
|
||||||
|
|
||||||
|
**AIAssistantModule**: LLM-powered contextual interventions
|
||||||
|
- Claude API integration
|
||||||
|
- Context-aware suggestions
|
||||||
|
- Intelligent document retrieval
|
||||||
|
|
||||||
|
**LanguageLearningModule**: Language practice and learning
|
||||||
|
- Conversation in target language
|
||||||
|
- Vocabulary tracking
|
||||||
|
- Progress monitoring
|
||||||
|
|
||||||
|
**DataModule**: SQLite persistence
|
||||||
|
- Task history
|
||||||
|
- Session analytics
|
||||||
|
- Configuration backup
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- CMake 3.20+
|
||||||
|
- C++17 compiler (GCC/Clang)
|
||||||
|
- GroveEngine (included via symlink)
|
||||||
|
|
||||||
|
### Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Configure
|
||||||
|
cmake -B build
|
||||||
|
|
||||||
|
# Build everything
|
||||||
|
cmake --build build -j4
|
||||||
|
|
||||||
|
# Build modules only (for hot-reload workflow)
|
||||||
|
cmake --build build --target modules
|
||||||
|
|
||||||
|
# Run
|
||||||
|
./build/aissia
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hot-Reload Workflow
|
||||||
|
|
||||||
|
1. Start AISSIA: `./build/aissia`
|
||||||
|
2. Edit a module: `src/modules/SchedulerModule.cpp`
|
||||||
|
3. Rebuild: `cmake --build build --target modules`
|
||||||
|
4. **Module reloads automatically with state preserved**
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
Configuration files in `config/`:
|
||||||
|
|
||||||
|
**scheduler.json**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"hyperfocusThresholdMinutes": 120,
|
||||||
|
"breakReminderIntervalMinutes": 45,
|
||||||
|
"breakDurationMinutes": 10,
|
||||||
|
"workdayStartHour": 9,
|
||||||
|
"workdayEndHour": 18
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**notification.json**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"language": "fr",
|
||||||
|
"silentMode": false,
|
||||||
|
"ttsEnabled": false,
|
||||||
|
"maxQueueSize": 50
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- **[docs/README.md](docs/README.md)**: Project documentation and architecture
|
||||||
|
- **[docs/GROVEENGINE_GUIDE.md](docs/GROVEENGINE_GUIDE.md)**: Complete GroveEngine user guide
|
||||||
|
- **[CDCDraft.md](CDCDraft.md)**: Detailed requirements specification (French)
|
||||||
|
|
||||||
|
## Development Philosophy
|
||||||
|
|
||||||
|
### MVP-First
|
||||||
|
|
||||||
|
- **Phase 1 (Required)**: Local Windows mode only
|
||||||
|
- **Phase 2+ (Optional)**: Cloud features if needed
|
||||||
|
- **Configuration-Driven**: 90% of needs via JSON
|
||||||
|
- **Simplicity First**: Complexity emerges from interaction
|
||||||
|
|
||||||
|
### Module Development
|
||||||
|
|
||||||
|
Each module is a self-contained unit (~200-300 lines):
|
||||||
|
|
||||||
|
1. Implements `IModule` interface
|
||||||
|
2. Pure business logic (no infrastructure code)
|
||||||
|
3. Communicates via `IIO` pub/sub
|
||||||
|
4. Serializes state for hot-reload
|
||||||
|
5. Configurable via `IDataNode`
|
||||||
|
|
||||||
|
See `docs/GROVEENGINE_GUIDE.md` for detailed module development guide.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
AISSIA runs on a simple loop (10Hz for assistant workload):
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Main Loop (10Hz) │
|
||||||
|
│ │
|
||||||
|
│ ┌────────────────────────────────────┐ │
|
||||||
|
│ │ 1. Check for module file changes │ │
|
||||||
|
│ │ 2. Hot-reload if modified │ │
|
||||||
|
│ │ 3. Process all modules │ │
|
||||||
|
│ │ 4. Route inter-module messages │ │
|
||||||
|
│ │ 5. Sleep to maintain 10Hz │ │
|
||||||
|
│ └────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
Modules communicate via topics:
|
||||||
|
- `scheduler:hyperfocus_detected` → NotificationModule alerts user
|
||||||
|
- `notification:alert_sent` → DataModule logs event
|
||||||
|
- `aiassistant:suggestion` → NotificationModule displays suggestion
|
||||||
|
|
||||||
|
## Technical Stack
|
||||||
|
|
||||||
|
- **Core**: C++17
|
||||||
|
- **Module System**: GroveEngine
|
||||||
|
- **Logging**: spdlog
|
||||||
|
- **Data Format**: JSON (nlohmann/json)
|
||||||
|
- **Build**: CMake 3.20+
|
||||||
|
- **Future**: SQLite (DataModule), Claude API (AIAssistantModule)
|
||||||
|
|
||||||
|
## Roadmap
|
||||||
|
|
||||||
|
- [x] Project setup with GroveEngine
|
||||||
|
- [x] SchedulerModule (time management & hyperfocus)
|
||||||
|
- [x] NotificationModule (alerts & TTS)
|
||||||
|
- [ ] AIAssistantModule (LLM integration)
|
||||||
|
- [ ] LanguageLearningModule (language practice)
|
||||||
|
- [ ] DataModule (SQLite persistence)
|
||||||
|
- [ ] Windows Toast notifications
|
||||||
|
- [ ] Real TTS integration
|
||||||
|
- [ ] Claude API integration
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
To be determined
|
||||||
|
|
||||||
|
## Links
|
||||||
|
|
||||||
|
- **GroveEngine**: [../GroveEngine](../GroveEngine)
|
||||||
|
- **Claude Code**: https://docs.claude.com/en/docs/claude-code
|
||||||
186
docs/project-overview.md
Normal file
186
docs/project-overview.md
Normal file
@ -0,0 +1,186 @@
|
|||||||
|
# AISSIA - Vue d'Ensemble du Projet
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
AISSIA 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
|
||||||
|
|
||||||
|
```
|
||||||
|
Aissia/
|
||||||
|
├── 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.
|
||||||
Loading…
Reference in New Issue
Block a user