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

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

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

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)

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)

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)

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)

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

// 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 :

# 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 :

# 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 :

// 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 :

# 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

// ✅ 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};
    }
};

// ❌ 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

# 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

// 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

// 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

// 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