5. High-Level Design

Cette section décrit l'architecture macroscopique d'ECHO v5. Le système est conçu comme une chaîne de traitement séquentielle et sécurisée, où la donnée transite à travers de multiples couches de souveraineté et d'isolation avant d'atteindre le grand modèle de langage (LLM).

Macro-Architecture Systémique (HLD)

L'infrastructure globale s'articule autour de cinq vecteurs de transmission majeurs, garantissant l'étanchéité entre l'interface utilisateur, la logique d'orchestration, et les capacités d'action distantes (Workers).

High-Level Design (HLD) : Transit de la Donnée [VUE MACROSCOPIQUE]

flowchart TD U(["👤 Utilisateur Client"]) subgraph PERIMETER ["🛡️ Périmètre de Sécurité"] BW{{"BunkerWeb
(WAF & Anti-Bot)"}} end subgraph INTERFACE ["🖥️ Couche Interface"] OWUI["Open WebUI
(Frontend HUD)"] end subgraph CORTEX ["🧠 Cerveau Cognitif (ECHO)"] direction TB F("Filtres Inlet
(Contexte & Compaction)") P("Echo Orchestrator
(Cortex & Suture)") F --> P end subgraph MEMORY ["🗄️ Persistance & Vectorisation"] RAG[("Base Vectorielle
(Qdrant)")] SQL[("Ombres Riches
(SQLite)")] end subgraph WORKERS ["🛠️ Workers Périphériques"] direction LR FASTAPI["Browser Worker
(FastAPI)"] N8N["N8N Worker
(Headless)"] MCP["MCP Broker"] end subgraph LLM ["☁️ Modèle de Langage"] GEMINI(("API Gemini
(HTTP/2 SSE)")) end U -->|1. Requête HTTPS| BW BW -->|2. Proxy Pass| OWUI OWUI -->|3. Payload Brut| F P -->|4. Suture & Audit| SQL P -->|5. Recherche Sémantique| RAG P -->|6. Délégation Asynchrone| FASTAPI P -->|6. Délégation Asynchrone| N8N P -->|7. Inférence & Outils| GEMINI classDef user fill:#0f172a,stroke:#3b82f6,color:#fff classDef waf fill:#7f1d1d,stroke:#ef4444,color:#fff classDef interface fill:#1e293b,stroke:#64748b,color:#fff classDef cortex fill:#1e1b4b,stroke:#8b5cf6,stroke-width:2px,color:#fff classDef memory fill:#422006,stroke:#f59e0b,color:#fff classDef workers fill:#064e3b,stroke:#10b981,color:#fff classDef llm fill:#4c1d95,stroke:#a855f7,color:#fff class U user class BW waf class OWUI interface class F,P cortex class RAG,SQL memory class FASTAPI,N8N,MCP workers class GEMINI llm

Écorché Structurel - Modules Python

Cette cartographie exhaustive représente les différents modules d'ECHO organisés par grands domaines de responsabilités. Chaque bloc regroupe les fonctions clés permettant au système d'opérer de manière autonome.

11-owui-filters
build_environment_domain.py
Amorçage domaines (Priorité 0)
tcp_keepalive_filter.py
Maintien des connexions longues
edge_embed_bridge_filter.py
Inférence WebGPU dans le navigateur
user_native_context_filter.py
Ancrage réglages utilisateur
context_compaction_filter.py
Rejeu Checkpoints & Compaction (Priorité 15)
new_context_filter.py
Smart Context, PIS & AEC XML
conversation_rag_filter.py
Indexation RAG O(1) asynchrone
app_drawer_filter.py
Tiroir d'actions rapides HUD
14-owui-libs
echo_auth.py
Authentification & Sécurité
echo_protocol.py
Traducteur universel API
echo_state_manager.py
Gestion mémoire SQLite & KV
echo_constants.py
Registre SSOT & Constantes
echo_aec.py
Orchestration & Drainage XML AEC
echo_browser_lib.py
Pilotage navigateur fantôme
echo_codex_git.py
Moteur Git Dulwich multi-workspaces
echo_core.py
Fonctions cognitives, Compaction & FIFO
echo_events.py
Moteur d'événements UI & UCTP
14-owui-libs (Suite)
echo_audio.py
Pont Audio In-Process (STT/TTS)
echo_gemini_client.py
Client HTTP/2 Gemini
echo_http.py
Requêtes HTTP asynchrones
echo_ingestion.py
Moteur d'ingestion de fichiers
echo_logger.py
Traçabilité et logs
echo_paths.py
Gestion des chemins système
echo_pkce_server.py
Serveur d'autorisation local
echo_prompts.py
Gabarits de prompts système
echo_skills.py
Gestionnaire de compétences
echo_ssh_tunnel.py
Tunnel sécurisé OAuth2
10-owui-pipes
echo_orchestrator.py
Cerveau principal du système
Reconstruction de l'historique
Lecture des réponses en direct
Choix automatique de l'IA
Fourniture du contexte
Interface HUD
echo_ui.py
Jauge de Tokens, Quotas & HUD
echo_visuals.py
Graphiques & Composants
Admin Manager
server.py (core / services / routes)
Gouvernance SSoT Fail-Closed
Élagage & Consolidation Lvl1→Lvl2
Workers & Couche de persistance (Docker)
SQLite Shadows
/users/{uid}/chats/{cid}/session.db
message_shadows + identity.db
Qdrant :6333
echo_meta_artifacts (permanent)
echo_session_rag (session)
Vault Fichiers
/users/{uid}/files/
Fichiers utilisateurs (pérennes)
Embedding :7997
Harrier-OSS-v1-0.6B
Edge Bridge / GGUF F16
SearXNG :8080
Métamoteur Web (.101)
Recherche Souveraine JSON
Browser Worker
Playwright Headless
Port 5002
Coding Worker
Sandbox Python/Node
Port 5000
N8N Worker
Orchestration Headless
Port 5003
MCP Broker
Proxy HTTP & Cache MSAL
Port 8000
Auth & Download
ECHO Auth IdP :8000
Download Broker Daemon

Concepts Structurants du Pipeline

⚔️ La Suture (Continuité Conversationnelle)

Nature : Mécanisme de reconstruction fidèle de l'historique.

Reconstruit l'historique complet de la session à partir des Ombres SQLite locales. Le Verrou de Version et le Verrou de Tour garantissent une reprise exacte au bit près tout en préservant le cache de préfixes du fournisseur Cloud. En cas d'édition manuelle d'un message, l'orchestrateur recalcule proprement la branche modifiée (Cold Recovery).

📡 L'AEC (Artéfacts Environnementaux et Contextuels)

Nature : Vecteurs proprioceptifs structurés en XML.

Informe le modèle en temps réel de son environnement d'exécution : directives système prioritaires (initialisation, mises à niveau, rappels d'alignement), identité cognitive, temporalité, localisation, contexte documentaire distillé, Checkpoint de continuité et événements système asynchrones.

🧱 Le Moulage (Smart Context RAG)

Nature : Pipeline d'ingestion documentaire sans saturation mémoire.

Au-delà de 32 Ko pour le texte ou 1 Mo pour le multimédia (et après conversion automatique des documents bureautiques en Markdown), le contenu est indexé dans la mémoire vectorielle de session et synthétisé sous forme d'aperçu structuré pour préserver l'attention du modèle.

📝 Le Draft (Brouillon Sémantique)

Nature : Enveloppe contextuelle préparée en amont de l'orchestrateur.

Assemble selon la hiérarchie stricte du PGCU les aperçus documentaires, les directives système ponctuelles, la requête utilisateur, les notifications d'événements système et les pièces jointes avant transmission au moteur d'inférence.

⛳ L'Ancre (Signature de Raisonnement)

Nature : Jeton cryptographique de continuité cognitive Gemini 3+.

Capturé et persisté localement à chaque tour de réflexion, il est restitué lors des appels d'outils successifs pour permettre au modèle de retrouver instantanément son état de raisonnement interne sans avoir à relire ses pensées brutes.

⚠ Distinct du Context Caching (cache implicite des activations clé/valeur côté Google).

Architecture Mémorielle Duale

ECHO opère deux collections vectorielles Qdrant physiquement isolées, vectorisées en 1024 dimensions par le modèle Harrier-OSS-v1-0.6B via le pont WebGPU du navigateur client ou le service d'embedding local. Aucune donnée ne quitte l'infrastructure.

🧠 Mémoire Organique à Long Terme

Portée : Par utilisateur — permanente et transverse à toutes les sessions.

Usage : Préférences personnelles (PACP), contraintes techniques, décisions structurelles et apprentissages méthodologiques (PRAC) gradués sur 5 niveaux d'importance (de 1 - Trivial dès la première observation jusqu'à 5 - Axiome sur injonction explicite ou invariant stratégique).

Priorisation Sémantique : Lors de la recherche, la pertinence thématique est pondérée par le niveau d'importance du souvenir afin qu'un Axiome prime systématiquement sur une observation Triviale.

Consolidation & Cycle de Vie : Fusion nocturne des observations récurrentes en souvenirs consolidés et élagage automatique selon l'ancienneté (de 30 jours pour un élément Trivial à 540 jours pour un Axiome).

⏱️ Mémoire Vectorisée de Session

Portée : Isolée par discussion (avec possibilité de recherche globale inter-sessions sur demande).

Usage : Indexation des fichiers volumineux, de l'historique conversationnel au fil de l'eau, des résultats de navigation web et des données intermédiaires d'analyse.

Cycle de Vie : Purgée automatiquement lors de la suppression de la discussion correspondante.

La Vallée de la Mort et la compensation RAG

Lorsque le contexte dépasse ~30 % de la fenêtre maximale, les informations des premiers tours deviennent progressivement moins accessibles au mécanisme d'attention. Les deux mémoires vectorielles constituent la réponse architecturale : la mémoire de session indexe proactivement les contenus volumineux et permet une lecture sémantique précise indépendante de la position dans l'historique, tandis que la mémoire organique restitue les préférences de l'utilisateur et l'expérience accumulée au fil des sessions précédentes.

Anatomie Détaillée d'une Requête (Le Chemin de la Donnée)

Ce diagramme de séquence retrace le cycle complet d'un tour de parole, des quatre phases distinctes : Préparation (Draft), Suture (Restauration), Inférence (Boucle outils) et Scellement.

Diagramme de Séquence : Pipeline de Bout en Bout [INLET ➔ SUTURE ➔ OUTLET]

sequenceDiagram autonumber box rgb(15, 23, 42) Utilisateur participant U as 👤 Utilisateur end box rgb(2, 6, 23) Middleware participant OWUI as 🖥️ Open WebUI end box rgb(30, 41, 59) ECHO Kernel participant F as 🌒 Filtre (Inlet) participant P as ⚙️ Orchestrateur (Pipe) participant DB as 🗄️ SQLite (Shadows) end box rgb(6, 78, 59) Sandbox participant T as 🛠️ Arsenal end box rgb(76, 29, 149) Cloud participant G as ☁️ Gemini API end U->>OWUI: Prompt + Fichiers (HTTPS) OWUI->>F: Interception hook.inlet() note over F,DB: PHASE 1 : PRÉPARATION, COMPACTION & DRAFT (PGCU) F->>DB: Rejeu / Compaction de Checkpoint (Priorité 15) & Vérification version F->>F: Sniffing MIME & Conversion Office (MarkItDown) F->>F: Moulage fichiers (32 Ko texte / 1 Mo média) → echo_session_rag F-->>OWUI: Injection AEC XML natif (Priorité 20) + Draft (metadata) OWUI->>P: Routage /api/chat/completions note over P,DB: PHASE 2 : SUTURE (BIT-PERFECT) & VERROU DE TOUR P->>DB: get_message_shadow(msg_id, updated_at) + purge_orphaned_events() DB-->>P: Parts JSON originales + Verrou de Version P->>DB: get_signature_by_id(message_id) + drain_pending_directives() DB-->>P: thoughtSignature + directives XML drainées atomiquement P->>P: Verrou turn_origin_model & mutation chirurgicale dernière occurrence AEC_modele note over P,G: PHASE 3 : INFÉRENCE & BOUCLE OUTILS P->>G: streamGenerateContent (HTTP/2 SSE + Circuit Breaker OAuth2) loop Appels d'outils G-->>P: functionCall (Tool Call Request) P->>T: Exécution isolée (API REST / Sandbox / MCP / N8N) T-->>P: Résultat multipart (echo_tool_multiparts) P->>G: functionResponse (Tool Call Response) end G-->>P: Génération finale (stream Markdown + thoughtSignature) note over P,DB: PHASE 4 : SCELLEMENT P->>DB: save_message_shadow(final_parts + updated_at) P->>DB: save_signature_by_id(message_id, thoughtSignature) P->>DB: save_cognitive_data(cumulative_hash, tool_io) P->>DB: index_suture(cumulative_hash, parent_hash) + save_session_setting() P-->>OWUI: Forward SSE Stream OWUI-->>U: Rendu HUD & Markdown

Topologie Réseau (Cluster Docker)

💡 Lecture d'architecte

Ce schéma représente la topologie réelle du cluster Docker ECHO. Le trafic WAN est filtré par BunkerWeb (WAF) si celui-ci est activé (optionnel, contrôlé via les scripts enable-bunkerweb.sh et disable-bunkerweb.sh). En cas d'activation, BunkerWeb délègue l'authentification (SSO & MFA) au module ECHO Auth. L'Arsenal (echo-browser-worker, echo-coding-worker, SearxNG) s'exécute sur un sous-réseau Docker privé sans accès entrant. Les volumes SQLite garantissent la persistance des données hors-conteneur. L'Admin Manager accède au Docker Daemon via /var/run/docker.sock (socket Unix monté en volume).

Network & System Topology (Domain-Driven IPAM) [MODE : DOCKER CLUSTER]

flowchart TB subgraph WAN ["🌐 ZONE 0 & 1 : WAN & EDGE WAF"] direction LR U(["👤 Client"]) == "HTTPS :443" ==> BW{{"🛡️ BunkerWeb WAF"}} AUTH["🔑 echo-auth-manager (.24 :8000)"] BW -. "Forward Auth /api/verify" .-> AUTH end subgraph APP ["🖥️ ZONE 2 : CORTEX OPEN WEBUI (.100 :8080 / hôte :3000)"] direction LR OWUI["🖥️ Open WebUI"] F("🌒 Filtres Inlet/Outlet") P("⚙️ Echo Orchestrator") AUD("🎙️ Pont Audio In-Process
(/echo/v1/audio)") SSH["🚇 SSH PKCE (:8020-8024)"] OWUI --> F --> P OWUI <--> AUD end subgraph DATA ["🗄️ ZONE 3 : PERSISTANCE & VECTORISATION"] direction LR SQL[("🗄️ SQLite WAL
(session.db & identity.db)")] QD[("🧠 Qdrant
(.103 :6333)")] EMB[("🔢 Embedding Worker
(.30 :7997)")] QD <--> EMB end subgraph SANDBOX ["🛠️ ZONE 4 : WORKERS ISOLÉS (echo-network & echo-sandbox)"] direction LR CW["🚀 Coding Worker
(.21 :5000 sandbox)"] BA["🌐 Browser Worker
(.22 :5002)"] MCP["🔌 MCP Broker
(.23 :8000)"] DL["⬇️ Download Broker
(.25 Daemon)"] N8N["⚙️ N8N Worker
(.26 :5003)"] SNG["🔍 SearXNG (.101 :8080)"] end subgraph MGMT ["⚙️ ZONE 5 & 6 : ADMIN (.20 :3001) & SORTIE CLOUD"] direction LR AM["📊 Admin Manager"] == "Socket" ==> DOCKER("🐋 Docker Daemon") GEMINI(("🌩️ Gemini / Code Assist
[HTTP/2 SSE]")) WWW(("🌍 Web Public
[HTTPS]")) end BW ==> OWUI BW -. "Admin" .-> AM U -. "Tunnel PKCE" .-> SSH P ==> SQL & QD P ==> CW & BA & MCP & N8N & SNG P & AUD == "HTTP/2" ==> GEMINI BA & N8N --> DL BA & SNG ==> WWW classDef node fill:#1e293b,stroke:#475569,stroke-width:2px,color:#f8fafc classDef db fill:#0f172a,stroke:#f59e0b,stroke-width:2px,color:#f8fafc classDef core fill:#172554,stroke:#60a5fa,stroke-width:2px,color:#f8fafc classDef tool fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#f8fafc class U,BW,OWUI,AUTH,AM,DOCKER,SSH node class SQL,QD,EMB db class F,P,AUD core class BA,CW,MCP,N8N,SNG,DL tool

Schéma de Persistance (Ombres Riches)

ECHO conserve une mémoire inaltérable de chaque conversation sous forme d'Ombres Riches en mode SQLite WAL. Ces empreintes contiennent les parts multimodales, le registre unifié des ressources et les signatures cognitives, reliés par une chaîne de hachage de Merkle (suture_index) garantissant la continuité bit-perfect de la session.

Entity-Relationship Diagram (ERD) [SCHÉMA SQL - RICH SHADOWS]

erDiagram MESSAGE_SHADOWS { string message_id PK "UUID du message" string chat_id "ID de la session" string role "user ou model" json full_parts_json "Parts Gemini originales" integer updated_at "Verrou de Version" integer is_embedded "Flag RAG O(1) (0 ou 1)" } SUTURE_INDEX { string cumulative_hash PK "Hash SHA-256 cumulatif" string chat_id "ID de la session" string invariant_hash "Hash du contenu seul" string parent_hash "Hash cumulatif parent" string message_id FK "Message associé" integer timestamp "Horodatage de scellement" } COGNITIVE_SIGNATURES { string cumulative_hash PK "Lié au tour Merkle" string thought_signature "Ancre Gemini 3+" string message_id "Indexé (idx_sig_msg_id)" string model_id "Modèle générateur" integer updated_at "Tri chronologique DESC" } TOOL_JOURNAL { string cumulative_hash PK "Lié au tour Merkle" json io_json "Entrées et sorties outils" integer updated_at "Horodatage" } RICH_PAYLOADS { string invariant_hash PK "SHA-256 du contenu" json rich_parts_json "Parts multimodales" string message_id FK "Message porteur" integer created_at "Horodatage" } ECHO_RESOURCES { string id PK "UUID ressource ou AEC" string name "Nom fichier ou directive" string resource_type "codex, plan, media, aec_..." string status "Statut d'ingestion" string item_type "file ou directory" integer updated_at "Horodatage" } ECHO_SETTINGS { string key PK "turn_origin_model, context_stats, compaction_state..." string value "Valeur sérialisée KV" integer updated_at "Horodatage" } MESSAGE_SHADOWS ||--o{ SUTURE_INDEX : "indexé par" SUTURE_INDEX ||--o| COGNITIVE_SIGNATURES : "scelle" SUTURE_INDEX ||--o{ TOOL_JOURNAL : "journalise" MESSAGE_SHADOWS }|--o{ RICH_PAYLOADS : "enrichit" MESSAGE_SHADOWS ||--o{ ECHO_RESOURCES : "référence"

⚙️ Dossier d'Ingénierie & Spécifications (Librairies Partagées)

1. Authentification, Quotas & Crédits Cloud (`echo_auth.py`, `echo_pkce_server.py`, `echo_ssh_tunnel.py`)

Gère le cycle OAuth2 headless via Authorization Code + PKCE (RFC 7636) sur tunnel SSH éphémère (ports 8020–8024), le rafraîchissement proactif des tokens à 55 minutes et le fallback sur clés AI Studio. Interroge de manière non-bloquante l'endpoint :retrieveUserQuotaSummary (cache google_quota_summary) pour extraire les quotas glissants 5 heures (quota_5h_fraction, quota_5h_reset, quota_5h_disabled) et Hebdomadaire (quota_weekly_fraction, quota_weekly_reset), en gérant la convention d'omission Protobuf v3 (remainingFraction=0.0 par défaut lorsque le champ est absent) au profit de la Context Gauge.

2. Moteur de Protocole, Suture Bit-Perfect & Compaction (`echo_protocol.py`, `echo_core.py` & `echo_aec.py`)

Suture, Signatures & Drainage AEC : Orchestrator.prepare_context() reconstruit l'historique depuis message_shadows (dans /users/{uid}/chats/{cid}/session.db) sous contrôle du Verrou de Version (message_id + updated_at) et du Verrou de Tour (turn_origin_model), extrait la dernière thoughtSignature de cognitive_signatures par tri déterministe (ORDER BY updated_at DESC LIMIT 1, rattachée au premier functionCall), assemble le brouillon metadata._echo_user_parts_draft et draine atomiquement les directives et événements XML (<artifact id="AEC_...">) via EchoAEC.drain_pending_directives().
Traduction, Moulage & Pondération RAG : Convertit les identifiants abstraits ECHO vers le backend actif (AI Studio ou Code Assist) et normalise les schémas d'outils en camelCase (convert_owui_tools). Le pipeline echo_ingestion.py convertit les documents via MarkItDown, distille via MODEL_DISTILLATION dans <artifact id="AEC_smart_context"> et vectorise dans echo_session_rag ou echo_meta_artifacts (http://echo-embedding:7997/v1). Le reranking de echo_meta_artifacts applique score_pondéré = cos_score × MEMORY_IMPORTANCE_WEIGHTS[lvl] (où un Axiome niveau 5 à 1.70 surclasse un Trivial niveau 1 à 0.55).
Déballage Multimodal & FIFO Destructif : unbox_tool_output et wrap_tool_output extraient les médias echo_tool_multiparts et purgent les événements transitoires aec_event / aec_directive sans toucher aux ressources persistantes.
Compactage Contextuel In-Place (EchoCompactionEngine) : Déclenché automatiquement (seuil 45% → 25% de ECHO_MAX_CONTEXT_SIZE via context_compaction_filter.py, Priorité 15) ou manuellement (compact_context_action.py), le moteur opère une consolidation téléscopique à encombrement borné (MODEL_APOLLO, budget 32768 tokens) scellée dans echo_settings (clé compaction_state). Le filtre rejoue de manière déterministe la balise <artifact id="AEC_context_checkpoint"> sur le message pivot, tandis que echo_orchestrator.py re-scelle l'ombre dans message_shadows après nettoyage de la balise (strip_checkpoint_tag) pour préserver la pureté de la Suture.

3. Gestionnaire de Compétences (`echo_skills.py`)

Extrait les métadonnées sémantiques des fichiers de compétences dans l'espace utilisateur global et alimente dynamiquement les outils search_skill, read_skill et forge_skill.

4. Algorithmes de Hachage Merkle (`echo_state_manager.py`)

1. Invariant Hash : SHA-256(role + content_sorted + tool_io). Identité pure du tour, indépendante de sa position dans l'historique.

2. Cumulative Hash : SHA-256(invariant_hash + parent_cumulative_hash). ADN de la conversation. Tout changement dans l'historique invalide les hashes suivants.

✅ Exactitude - Cold Recovery

Le Verrou de Version compare le couple (message_id, updated_at) lors de la Suture. Si un message est modifié manuellement dans Open WebUI, l'Ombre SQLite correspondante est écartée, les événements postérieurs au t_pivot sont purgés via EchoAEC.purge_orphaned_events(), et le Pipe bascule en Cold Recovery tout en préservant la continuité de la session.

5. Pont Audio In-Process (`echo_audio.py` v1.4)

Injecté de manière idempotente en position 0 du routeur FastAPI d'Open WebUI via register_echo_audio_routes() (pour devancer le catch-all SPAStaticFiles), ce module expose les endpoints compatibles OpenAI sous /echo/v1/audio : transcription STT (/transcriptions) relayée vers Gemini MODEL_ZEPHYR (maxOutputTokens=8192, thinkingLevel="minimal", plafond 14 Mo, détection binaire des conteneurs WebM/WAV/OGG/FLAC/MP3/MP4 par sniff_audio_mime_type) et synthèse vocale TTS en streaming audio/mpeg (/speech) via Microsoft Edge Read-Aloud (edge-tts, voix fr-FR-VivienneMultilingualNeural, vitesse nominale 1.0, pitch feutré -2Hz).

← 4. Tutoriel Pratique 6. Communication Gemini →