aissia/docs/architecture/architecture-technique.md

# Architecture Technique - AISSIA

## Vision Globale

**Concept** : Assistant personnel intelligent basé sur l'architecture modulaire WarFactory pour développement rapide et hot-reload.

**Innovation clé** : Réutilisation de l'architecture WarFactory (moteur modulaire C++) pour créer un assistant personnel avec développement parallèle optimisé pour Claude Code.

## Architecture Système

### Core Interface Architecture

**ARCHITECTURE MODULAIRE** - Système modulaire optimisé pour le développement avec Claude Code.

#### Les 5 Interfaces Fondamentales

```cpp
ICoordinationModule → Orchestrateur global système (MainServer, déploiement, config)
IEngine            → Coordination locale (DebugEngine → HighPerfEngine → DataOrientedEngine)
IModuleSystem      → Stratégie d'exécution (Sequential → Threaded → Multithread → Cluster)
IModule            → Logique métier pure (MonitoringModule.so, SchedulerModule.so, AIModule.so)
IIO                → Communication (IntraIO → LocalIO → NetworkIO)
```

#### Architecture de Déploiement Global

```
MainServer Process:
├── CoordinationModule (Global Orchestrator)
│   ├── Loads appconfig.json via IDataTree
│   ├── Manages local IEngine + modules
│   └── Launches remote servers + engines (optionnel)
├── Local IEngine (manages local modules)
│   ├── IModuleSystem (Sequential/Threaded/etc.)
│   └── Local Modules (.so/.dll files)
└── Remote Servers (optionnel - mode cloud)
    ├── Remote IEngine (manages remote modules)
    ├── IModuleSystem (execution strategy)
    └── Remote Modules (.so files)
```

#### Séparation des Responsabilités

**IEngine** : Orchestration et coordination
- DebugEngine : Développement et test (step-by-step, verbose logging)
- HighPerfEngine : Production optimisée (threading, memory management)
- DataOrientedEngine : Scale massive (SIMD, cluster distribution - optionnel)

**IModuleSystem** : Stratégies d'exécution
- SequentialModuleSystem : Debug/test (1 module à la fois)
- ThreadedModuleSystem : Chaque module dans son thread
- MultithreadedModuleSystem : Pool de threads pour tasks
- ClusterModuleSystem : Distribution sur plusieurs machines (optionnel)

**ICoordinationModule** : Orchestrateur global système
- Premier module lancé, dernier fermé
- Charge appconfig.json via IDataTree
- Déploie modules selon topologie (local/distant)
- Synchronise configurations entre tous les modules

**IModule** : Logique métier pure
```cpp
class IModule {
    virtual json process(const json& input) = 0;  // PURE FUNCTION
    virtual void setConfiguration(const IDataNode& configNode, IIO* io, ITaskScheduler* scheduler) = 0;
    virtual const IDataNode& getConfiguration() = 0;
    virtual json getHealthStatus() = 0;  // Detailed JSON status
    virtual void shutdown() = 0;
};
```

**Contraintes strictes** :
- **200-300 lignes maximum** par module
- **Aucune dépendance infrastructure** (threading, network, etc.)
- **JSON in/out uniquement** pour communication
- **Logic métier pure** sans effets de bord

### Contrainte Design Fondamentale : Task-Centric Logic

**CRITICAL** : Les modules doivent être conçus avec une **task-centric logic** dès le début pour supporter l'évolution progressive.

#### Task-Centric Logic Requirements
```cpp
class IModule {
    virtual json process(const json& task) = 0;  // TASK-CENTRIC DESIGN
    // task = unité de travail atomique, pas state global
    // Permet distribution future sans refactoring
};
```

**Implications design** :
- **Stateless preferred** : Tasks indépendantes autant que possible
- **Granularité fine** : 1 task = 1 opération logique discrète
- **Context minimal** : Task contient tout le contexte nécessaire
- **Results self-contained** : Output complet pour la task

#### Évolution Progressive Détaillée

**Phase 1 : Debug/Prototype (MVP AISSIA)**
```cpp
DebugEngine + SequentialModuleSystem + IntraIO
```
- **Execution** : Tasks traitées séquentiellement par même thread
- **Flow** : Module1.process(task1) → Module2.process(task2) → Module3.process(task3)
- **Avantage** : Debug step-by-step, Claude Code friendly
- **Task-centric** : Prépare la distribution future

**Phase 2 : Optimization (optionnel)**
```cpp
DebugEngine + ThreadedModuleSystem + IntraIO
```
- **Execution** : Tasks distribuées par module sur threads dédiés
- **Flow** : Module1(Thread A), Module2(Thread B) - tasks parallèles
- **Avantage** : Performance sans changer task logic

**Phase 3 : Production (optionnel)**
```cpp
HighPerfEngine + MultithreadedModuleSystem + LocalIO
```
- **Execution** : **Task queue + worker thread pool**
- **Flow** : Tasks distribuées sur pool selon disponibilité et priorité
- **Avantage** : Load balancing automatique des tasks

**Phase 4 : Cloud Scale (optionnel)**
```cpp
DataOrientedEngine + ClusterModuleSystem + NetworkIO
```
- **Execution** : **Tasks distribuées sur machines différentes**
- **Flow** : MonitoringTasks (Server A), AITasks (Server B)
- **Avantage** : Scale horizontal transparent grâce au task-centric design

**Évolution Garantie** : Le task-centric design initial permet l'évolution automatique vers la distribution sans réécriture de logique métier !

**IIO** : Couche transport
- IntraIO : Appel direct (même processus)
- LocalIO : Named pipes/sockets (même machine)
- NetworkIO : TCP/WebSocket (réseau)

#### Évolution Progressive Sans Régression

```cpp
// Phase 1 : Prototype (MVP AISSIA)
DebugEngine + SequentialModuleSystem + IntraIO
→ Développement ultra-rapide, Claude Code 100% focus logique

// Phase 2 : Optimization (optionnel)
DebugEngine + ThreadedModuleSystem + IntraIO
→ Performance boost sans changer 1 ligne de logique

// Phase 3 : Production (optionnel)
HighPerfEngine + MultithreadedModuleSystem + LocalIO
→ Scale transparent, MonitoringModule.so inchangé

// Phase 4 : Cloud Scale (optionnel)
DataOrientedEngine + ClusterModuleSystem + NetworkIO
→ Distribution massive, même logique métier
```

**Avantage révolutionnaire** : Les modules de logique métier (MonitoringModule.so, AIModule.so) restent identiques à travers toutes les phases d'évolution !

### Build Autonome par Module

**Classification :** HIGH - Implémentation prioritaire
**Principe :** `cmake .` depuis chaque module, zéro dépendance parent

#### Structure de Build Autonome

**Directory pattern requis :**
```
modules/scheduler/
├── CMakeLists.txt       # Autonomous build config
├── CLAUDE.md           # Module-specific instructions
├── src/
│   ├── SchedulerModule.cpp  # 200 lignes max
│   └── SchedulerModule.h    # Interface pure
├── tests/
│   └── scheduler_test.cpp   # Standalone testing
└── build/             # Local build artifacts
    └── scheduler.so  # Hot-reloadable module
```

**CMake autonome pattern :**
```cmake
# NEVER cmake .. - ALWAYS cmake .
cmake_minimum_required(VERSION 3.20)
project(SchedulerModule)

# Self-contained dependencies
find_package(nlohmann_json REQUIRED)

# Pure module compilation
add_library(scheduler MODULE src/SchedulerModule.cpp)
target_link_libraries(scheduler nlohmann_json::nlohmann_json)

# Standalone testing
add_executable(scheduler-test tests/scheduler_test.cpp)
target_link_libraries(scheduler-test scheduler)
```

#### Implications Développeurs

**Architecture modulaire pure :**
- **Zero dependencies up** : Jamais `#include "../core/engine.h"`
- **Self-contained units** : Chaque module = micro-projet autonome
- **Interface contracts only** : Communication via JSON/IModule uniquement
- **Infrastructure agnostic** : Module ignore engine/system hosting

**Workflow Claude Code révolutionnaire :**
- **Micro-context focus** : 200-300 lignes + CMakeLists.txt + CLAUDE.md total
- **Parallel instances** : 3+ Claude Code travaillant simultanément
- **Build verification** : `cmake . && make` validation automatique
- **Development velocity** : 10x improvement mesurable

**Exemple concret** : SchedulerModule, LanguageLearningModule peuvent être développés en parallèle car complètement isolés

#### Contraintes Strictes CRITICAL

**NEVER patterns (violations = build failure) :**
- `cd ..` ou `cmake ..` - Toujours rester dans module directory
- `#include "../"` - Aucune référence parent directory
- Dependency sur `core/` ou `shared/` - Module = island complet
- Shared C++ objects - JSON communication exclusive

**ALWAYS patterns (required for autonomy) :**
- `cd modules/monitoring/ && cmake .` - Build depuis module directory
- Interface-only dependencies - IModule.h via find_package uniquement
- Local build artifacts - `build/` directory dans module
- Standalone testing - Tests s'exécutent sans infrastructure

### Hot-Reload Infrastructure

**Classification :** HIGH - Implémentation prioritaire
**Principe :** Remplacement temps réel modules DLL/SO avec sauvegarde état

#### Architecture Hot-Reload

**Platform Support :**
- **Primary** : .dll (Windows development natif)
- **Secondary** : .so (Linux server/dev support)
- **Unified interface** : Même mécanisme, extension différente

**Workflow cible :**
```bash
# Edit SchedulerModule.cpp → Save → Auto-rebuild scheduler.dll
# Système détecte changement → Hot-reload → App continue
# <5 secondes total sans interruption (target: 0.4ms reload)
```

#### Mécanisme Technique

**Windows DLL Hot-Reload :**
```cpp
// State preservation avant reload
json moduleState = currentModule->exportState();

// Hot-swap DLL
FreeLibrary(schedulerDLL);                    // Décharge ancienne
schedulerDLL = LoadLibrary(L"scheduler.dll"); // Charge nouvelle version

// State restoration après reload
auto createFunc = GetProcAddress(schedulerDLL, "CreateSchedulerModule");
newModule = createFunc();
newModule->importState(moduleState);     // Restore état
```

**Build DLL autonome :**
```cmake
# modules/scheduler/CMakeLists.txt
add_library(scheduler SHARED src/SchedulerModule.cpp)
set_target_properties(scheduler PROPERTIES
    SUFFIX ".dll"                        # Windows primary
    POSITION_INDEPENDENT_CODE ON         # Linux SO ready
)
```

#### Performance Achievements (WarFactory Validated)

**Benchmark Results :**
- **Average Hot-Reload**: **0.4ms**
- **Best Time**: **0.055ms**
- **Complete 5-cycle test**: **2ms total**
- **Classification**: **🚀 BLAZING** (Sub-20ms target exceeded by 50x)
- **State Persistence**: **PERFECT** - all module state preserved

### Contrainte Claude Code : Micro-Context Optimization

**CRITICAL** : Modules limités à **200-300 lignes maximum** pour optimiser l'efficacité de développement avec Claude Code.

#### Problème Résolu : Context Window
- **Avant** : Claude Code doit comprendre 50K+ lignes interconnectées
- **Après** : Claude Code travaille sur modules isolés de 200-300 lignes max
- **Résultat** : **250x réduction** de la complexité contextuelle

#### Architecture Micro-Context
```cpp
// ✅ CORRECT - Module optimisé Claude Code
class SchedulerModule : public IModule {
    json process(const json& task) override {
        // 200 lignes de pure scheduling logic
        // Aucune infrastructure, networking, threading
        // JSON in/out uniquement
        return {"next_task": "Break", "duration_minutes": 10};
    }
};
```

```cpp
// ❌ INCORRECT - Trop complexe pour Claude Code
class MegaSchedulingSystem {
    // 5000+ lignes avec networking, threading, UI, etc.
    // Claude Code ne peut pas appréhender efficacement
};
```

#### Workflow Révolutionnaire : Développement Parallèle
```bash
# Instance Claude Code A - 250 lignes context
cd modules/scheduler/
# Context: CLAUDE.md (70) + SchedulerModule.cpp (150) + IModule.h (30)

# Instance Claude Code B - 230 lignes context
cd modules/ai-assistant/
# Context: CLAUDE.md (60) + AIAssistantModule.cpp (140) + IModule.h (30)

# Instance Claude Code C - 240 lignes context
cd modules/language-learning/
# Context: CLAUDE.md (65) + LanguageLearningModule.cpp (145) + IModule.h (30)
```

## Modules AISSIA (Exemples)

L'architecture modulaire permet de créer des modules spécialisés pour AISSIA :

### SchedulerModule
- **Responsabilité** : Planning intelligent des tâches
- **Scope** : Gestion tâches, priorités, deadlines, optimisation planning
- **Frequency** : 0.1-1Hz (mises à jour planning)
- **Communication** : JSON tasks, schedules

### AIAssistantModule
- **Responsabilité** : Intelligence conversationnelle et interventions
- **Scope** : Génération interventions via LLM, analyse contexte, décisions proactives
- **Frequency** : Sur événement (détection hyperfocus, etc.)
- **Communication** : JSON prompts, responses

### NotificationModule
- **Responsabilité** : Alertes et notifications utilisateur
- **Scope** : TTS, notifications système, rappels visuels/sonores
- **Frequency** : Sur événement
- **Communication** : JSON notification requests

### DataModule
- **Responsabilité** : Persistance et historique
- **Scope** : SQLite storage, métriques, analytics
- **Frequency** : Asynchrone (writes en batch)
- **Communication** : JSON data operations

### LanguageLearningModule
- **Responsabilité** : Apprentissage et pratique de langues étrangères
- **Scope** : Détection contexte d'apprentissage, conversation dans langue cible, corrections intelligentes
- **Frequency** : Sur événement (détection app apprentissage, conversation utilisateur)
- **Communication** : JSON avec état progression, dialogues bilingues
- **Intégration** : Permet à AIAssistantModule de dialoguer dans la langue apprise

## Architecture Communication

### Communication Modulaire

**Protocole uniforme** : JSON-only entre tous les modules via interfaces IIO

### Mode Local (MVP AISSIA)

**Architecture :**
- Tous modules locaux (IntraIO)
- Aucun réseau requis (sauf appels LLM pour AIAssistantModule)
- Performance maximale
- Privacy garantie (données utilisateur jamais uploadées)

### Mode Cloud (Optionnel Phase 2+)

**Architecture :**
- Modules temps réel locaux (Scheduler, Notification)
- Modules IA distribués (AIAssistant, LanguageLearning sur serveur)
- Communication via NetworkIO
- Hybrid processing (client-side + server-side)

## Avantages Architecture Modulaire

### Développement Claude Code Optimisé
- **Contextes micro** : 200-300 lignes par module vs 50K+ lignes système monolithique
- **Build autonome** : `cd modules/monitoring/ && cmake .` - zéro dépendance parent
- **Hot-reload** : Modifications instantanées sans restart système (0.4ms)
- **Développement parallèle** : Multiple instances Claude Code simultanées

### Performance & Scalabilité
- **Évolution progressive** : Debug → Production → Cloud sans réécriture
- **Module isolation** : Failures localisées, pas de cascade
- **Infrastructure hot-swappable** : Change performance sans affecter logique métier

### Maintenance & Evolution
- **Testing isolé** : Chaque module testable indépendamment
- **Migration zero-risk** : A/B testing, fallback automatique
- **Code reuse** : Modules réutilisables entre projets

## Development Philosophy

### Backward Compatibility Framework
**Proxy pattern ancien→nouveau coexistence**

```cpp
// Backward compatibility via proxy pattern
class LegacyMonitoringAdapter : public IModule {
    std::unique_ptr<OldMonitoringSystem> legacySystem;
    std::unique_ptr<NewMonitoringModule> modernSystem;
    bool useModern = false;

public:
    json process(const json& input) override {
        if (useModern && modernSystem->isReady()) {
            try {
                return modernSystem->process(input);
            } catch (const std::exception&) {
                // Fallback to legacy on failure
                return legacySystem->processLegacy(convertToOldFormat(input));
            }
        }
        return legacySystem->processLegacy(convertToOldFormat(input));
    }

    void enableModernSystem() { useModern = true; }
    void fallbackToLegacy() { useModern = false; }
};
```

**Benefits Architecture :**
- **Zero-risk migration** : Ancien système reste fonctionnel
- **A/B testing** : Switch runtime entre old/new
- **Progressive rollout** : Migration progressive users
- **Instant rollback** : Retour automatique si problème

### Configuration-Driven Development
**90% des besoins via config JSON, pas de complexité excessive**

```json
// Config-driven behavior via JSON
{
  "scheduler": {
    "work_session_minutes": 50,
    "break_minutes": 10,
    "max_hyperfocus_hours": 2,
    "daily_tasks": []
  },
  "ai_assistant": {
    "model": "claude-haiku-4.5",
    "intervention_style": "gentle",
    "max_words": 20
  },
  "language_learning": {
    "target_languages": ["en", "es"],
    "practice_during_breaks": true,
    "bilingual_mode": false
  }
}
```

**Architecture Benefits :**
- **90% customization needs** : Config JSON couvre la majorité
- **Zero complexity** : Pas infrastructure modding complexe
- **Claude-friendly** : Config changes = instant AI comprehension
- **Runtime modification** : Hot-reload configs sans restart

### "Complexity through Simplicity"
**Complexité émerge de l'interaction de modules simples**

```cpp
// Simple scheduler module (200 lines)
class SchedulerModule : public IModule {
    json process(const json& input) override {
        // Simple logic: manage tasks, priorities, timing
        return processSimpleScheduling(input);
    }
};

// Simple AI module (250 lines)
class AIAssistantModule : public IModule {
    json process(const json& input) override {
        // Simple logic: analyze context, generate intervention
        return processSimpleAI(input);
    }
};

// Complex behavior emerges from interaction
// Scheduler + AI = Smart interruptions based on planning
// LanguageLearning + AI = Intelligent bilingual conversations
// Scheduler + AI + LanguageLearning = Proactive learning assistant
```

**Architecture Benefits :**
- **Claude comprehension** : Each module easily understood by AI
- **Debugging simplicity** : Issues isolated to specific modules
- **Testing granularity** : Simple modules = simple tests
- **Development velocity** : Small contexts = fast iteration