smart_ide/docs/system-architecture.md

Architecture système — IDE, agents, runtime, mémoire

Vue produit multi-environnements, SSO et option navigateur : platform-target.md. Architecture écosystème + synchronisation (projets externes, API IA, hôte) : ecosystem-architecture-and-sync.md.

Objectifs du projet (rappel)

• Interaction : environnement orienté intentions et opérations (grammaire de commandes), pas une navigation fichier comme flux nominal ; mode expert pour l’arborescence. Voir ux-navigation-model.md.
• IA et mémoire : Ollama pour l’inférence locale ; AnythingLLM pour le RAG et la mémoire documentaire par projet ; les agents ia_dev restent le noyau métier et opératoire.
• Encadrement : OpenShell / policy-runtime (sandboxes, droits nommés, refus explicites, pas de fallback implicite non spécifié).
• Édition : socle applicatif Lapce sous core_ide/ (clone local hors index Git) — voir core-ide.md.
• Métier documentaire : ONLYOFFICE pour les flux bureautiques riches ; services/local-office/ pour une API programmatique (docx via commandes, stockage local, clés API) — voir features/local-office.md.
• Déploiement cible : soit poste Linux client + SSH vers un serveur (socle IA + repos), soit machine IA unique (Ollama et AnythingLLM sur le même hôte que les services). Les deux variantes sont décrites dans deployment-target.md. Les déploiements test / pprod / prod : platform-target.md.

Monorepo unique

Le référentiel de vérité pour l’écosystème décrit ici est un seul dépôt Git (smart_ide) : specs, services locaux, scripts, documentation, et arborescence éditeur vendue. Les produits et livrables 4NK ne sont pas hébergés sur GitHub ; la forge canonique est interne (ex. Gitea). Les dépôts publics (Lapce, bibliothèques Python, etc.) ne sont que des amonts éventuels pour import ou relecture, pas des cibles de publication obligatoires.

Conséquences :

• Les répertoires sous services/ font partie du même cycle de vie que le reste du monorepo (revue, déploiement, systemd).
• core_ide/ est un clone local de l’éditeur Lapce (socle applicatif), présent dans l’arborescence du monorepo sur disque ; il est exclu de l’index Git du parent par volumétrie (voir racine .gitignore). Mise à jour : procédure dans core-ide.md.
• ia_dev est un répertoire versionné dans ce monorepo (évolution historique depuis le dépôt forge 4nk/ia_dev) ; intégration et journaux : ia_dev-module.md, repo/ia-dev-smart-ide-integration.md, repo/logs-directory.md. Un service HTTP ia-dev-gateway (features/ia-dev-service.md) exposera le registre et les exécutions agents.
• Orchestrateur HTTP : features/orchestrator-api.md — serveur stub sous services/smart-ide-orchestrator/ ; routage intentions → Ollama, AnythingLLM, micro-services, ia-dev-gateway (forward HTTP à compléter).

Cartographie des ressources (arborescence)

Chemin	Rôle dans l’architecture
docs/ , docs/features/	Documentation technique et fonctionnalités ; point d’entrée unique pour les specs
services/langextract-api/	Extraction structurée depuis texte (LLM), API HTTP locale pour gateway / outils
services/agent-regex-search-api/	Recherche regex sur fichiers via ripgrep, périmètre borné par REGEX_SEARCH_ROOT
services/claw-harness-api/	Harnais optionnel multi-fournisseur (amont claw-code) + proxy ; gabarits sans Anthropic
services/repos-devtools-server/	Outillage Git HTTP local (clone, liste, chargement de dépôts sous racine contrôlée)
core_ide/	Sources Lapce — socle applicatif (build éditeur, personnalisations) — clone amont, hors index du parent
services/anythingllm-devtools/	HTTP : AnythingLLM + repos-devtools + RAG initial (.4nkaiignore) — API/anythingllm-devtools-api.md
services/carbonyl/	Navigateur terminal Chromium (Carbonyl) ; sous-module upstream/ ; prévisualisation test — repo/service-carbonyl.md
services/pageindex/	Index sémantique arborescent PDF/MD (PageIndex) ; sous-module upstream/ ; CLI — repo/service-pageindex.md
services/chandra/	OCR PDF/images → MD/HTML/JSON (Chandra) ; sous-module upstream/ ; CLI — repo/service-chandra.md
scripts/ , setup/ , systemd/	Installation hôte, scripts d’exploitation, unités utilisateur pour services
cron/	Pull Git planifié des clones décrits par projects/<id>/conf.json (project_path) — repo/cron-git-pull.md
services/local-office/	API REST Office (upload, commandes docx, stockage SQLite + fichiers) ; complément programmatique à ONLYOFFICE
services/docv/	Contrat d’intégration docv (hors monorepo) ; données projet sous ../projects/<id>/data/ ; pas de code applicatif docv ici — features/docv-service-integration.md
projects/<id>/ (racine monorepo)	Confs seules pour ia_dev (conf.json) — pas les clones Git ; clones typiquement sous ../projects/ ou autre racine ; voir repo/projects-directory.md
ia_dev/	Agents, déploiements — exécution sous policy ; ia_dev/projects/<id> peut pointer vers ../../projects/<id> (lien) ; voir ia_dev-module.md
services/ia-dev-gateway/	Gateway HTTP (stub runner) : registre agents .md, runs, SSE — features/ia-dev-service.md
services/smart-ide-orchestrator/	Routage intentions (stub forward) — features/orchestrator-api.md

Environnements test, pprod, prod

Chaque environnement possède ses URLs, secrets et politiques (AnythingLLM, tokens micro-services, OIDC front — docv). Pas de configuration sensible dans le dépôt : .secrets/<env>/ ou variables d’hébergement. Détail : platform-target.md.

Module ia_dev dans ce dépôt

Le répertoire ./ia_dev fait partie du dépôt smart_ide (référence historique : 4nk/ia_dev sur la forge). Sur le serveur SSH, l’agent gateway et les outils peuvent pointer vers ce chemin comme racine d’exécution des agents (scripts invoqués depuis la racine ia_dev). Voir ia_dev-module.md et repo/ia-dev-smart-ide-integration.md.

Répartition physique (première cible)

Pour le premier déploiement, un poste Linux (client) établit des sessions SSH vers un serveur qui concentre :

• Ollama, AnythingLLM (et extensions du socle IA) ;
• les dépôts et l’exécution des agents / OpenShell sur chemins autorisés.

L’éditeur et une partie de l’UX peuvent rester sur le client ; le gateway, le policy-runtime et les knowledge-services (fichiers RAG, workspaces AnythingLLM) sont cohérents côté serveur, sauf architecture hybride explicitement documentée. Voir deployment-target.md.

Couches fonctionnelles (vue cible)

Couche	Rôle
Agents ia_dev	Noyau métier et opératoire (existant) ; sous-agents, recettes, tools
OpenShell	Sécurité et exécution : sandboxes, politiques, résolution contrôlée
Éditeur (ex. Lapce)	Interaction : texte léger, terminal, palette, timeline, UX intentionnelle
Orchestrateur maison	Routage : pas « d’intelligence » au sens LLM, mais décision de flux
Ollama	Backend d’inférence locale
AnythingLLM	Mémoire documentaire et RAG ; un workspace par projet (anythingllm-workspaces.md)
ONLYOFFICE	Backend documentaire métier (documents, feuilles, présentations)

Flux type : demande utilisateur → orchestrateur → préparation (scripts / tools génériques) → agents → besoin LLM → Ollama ; besoin doc / RAG → AnythingLLM ; besoin bureautique riche → ONLYOFFICE ; besoin fichier Office manipulé par API (tiers, scripts, agents) → services/local-office/ (Local Office) ; besoin gestion documentaire métier docv → service docv (HTTP externe, données sous ../projects/<id>/data/ — features/docv-service-integration.md). Le backend docv peut s’appuyer sur les mêmes services pour des parcours IA par projet (features/docv-ai-integration.md).

Enrichissement possible du routage (sans changer le principe « orchestrateur = logique de flux, pas LLM ») :

• besoin d’entités typées dans du texte (preuves, champs métiers, grounding) → langextract-api puis post-traitement métier ;
• besoin de recherche symbolique (symboles, motifs, grep sémantique opérationnel) → agent-regex-search-api dans la limite du root autorisé ;
• besoin d’un runtime harnais unifié multi-modèle (hors Anthropic si politique projet) → claw-harness-api / binaire amont + proxy ;
• besoin de cloner ou rafraîchir un dépôt dans l’espace de code autorisé → repos-devtools-server.

Orchestrateur — décisions de routage

Décider notamment :

• quelle commande utilisateur appelle quel agent principal ;
• quel agent appelle quel sous-agent ;
• quand privilégier un script vs un tool générique vs ia_dev ;
• quand ia_dev peut escalader vers Ollama ;
• quand interroger AnythingLLM ;
• quand passer par ONLYOFFICE ;
• quand passer par Local Office (services/local-office/) (édition programmatique / intégration tierce légère) ;
• quand refuser.

Descripteur stable par agent

Chaque agent devrait exposer au minimum : nom, rôle, entrées, sorties, droits, dépendances, scripts appelés, modèles éventuels, préconditions, postconditions, timeouts, coût, niveau de risque.

Un protocole unique couvre les implémentations hétérogènes (script, workflow, wrapper d’outil, appel IA).

Hiérarchie agent → sous-agent : à formaliser explicitement pour éviter un graphe implicite ingouvernable.

Événements normalisés (exemples)

started, tool_selected, script_started, model_called, waiting_validation, completed, failed, rolled_back, artifact_created.

Sortie événementielle uniforme vers l’éditeur ; journalisation ; possibilité de rejouer, diagnostiquer, convertir en recette stable.

Sécurité — OpenShell central

• Chaque nouvelle résolution devrait pouvoir devenir recipe, tool ou sous-agent stable (travail des commandes UX de haut niveau).
• Les agents ne devraient pas exécuter directement sur l’hôte sans contrôle : sandboxes avec droits dérivés du type d’agent et du projet.

Exemples de profils de policy : lecture seule ; lecture + scripts locaux ; écriture bornée ; déploiement pprod / prod ; génération documentaire ; accès tickets ; accès base ; accès ONLYOFFICE ; accès API Local Office (clé API dédiée, périmètre réseau).

Pas de fallback implicite non spécifié : refus ou erreur explicite selon les règles du projet.

Couche de normalisation (registre agents)

Registre unifié des agents ia_dev, chacun exposé comme objet standardisé :

• identité, catégorie, commandes déclenchantes, permissions, environnements compatibles, mode d’exécution, outils requis, politiques OpenShell, formats d’entrée/sortie, stratégies de rejet (pas de fallback silencieux), journalisation, possibilité d’appeler d’autres agents.

Sans cette couche, l’IDE reste dépendant de conventions implicites du dépôt.

Agent gateway (adaptateur)

Ne pas brancher le dépôt ia_dev directement dans l’éditeur : passer par une agent gateway (implémentation cible : service ia-dev-gateway, API/ia-dev-gateway.md) qui :

1. Charge le registre
2. Valide les permissions
3. Résout les dépendances
4. Ouvre la sandbox OpenShell adaptée
5. Injecte le contexte autorisé
6. Lance l’agent
7. Capture les événements
8. Uniformise les sorties
9. Publie le flux vers l’éditeur
10. Journalise
11. Gère rollbacks et statuts

Modules logiciels (découpage)

Module	Responsabilité
editor-shell	Éditeur texte léger, terminal, explorer mode expert, onglets, palette de commandes, timeline, UX
agent-gateway	Adaptateur uniforme UX ↔ ia_dev
policy-runtime	OpenShell, profils de policy, providers, sandboxes, journaux
knowledge-services	AnythingLLM, mémoire projet, index documentaire, routage RAG
doc-services	ONLYOFFICE, flux present, write, sheet ; Local Office (services/local-office/, API upload / commandes docx)

Les agents restent le noyau opératoire ; les modules encadrent et exposent.

Micro-services HTTP locaux (extensions)

Services d’écoute sur 127.0.0.1 (souvent avec Authorization: Bearer) pour Lapce (une fois branché), scripts, gateway ou agents :

Service	Rôle	Doc
repos-devtools-server	Git : clone / liste / load sous REPOS_DEVTOOLS_ROOT	repo/service-repos-devtools.md
langextract-api	Extraction structurée depuis texte (wrapper LangExtract)	features/langextract-api.md
claw-harness-api	Harnais amont : build / politique sans Anthropic ; proxy optionnel vers serveur HTTP claw-code	features/claw-harness-api.md
agent-regex-search-api	Recherche regex sur fichiers via ripgrep sous REGEX_SEARCH_ROOT	features/agent-regex-search-api.md
local-office	API REST Office : upload, commandes docx ; auth X-API-Key (pas Bearer)	features/local-office.md , repo/service-local-office.md
ia-dev-gateway	Registre agents, runs stub, flux SSE (Node/TS)	features/ia-dev-service.md , API/ia-dev-gateway.md , repo/service-ia-dev-gateway.md
smart_ide-orchestrator	Routage intentions, timeline (Node/TS ; forward à compléter)	features/orchestrator-api.md , API/orchestrator.md , repo/service-smart-ide-orchestrator.md

Ces services sont des adapters : pas de logique métier produit au-delà de la validation d’entrée et de l’appel au moteur (Git, rg, LangExtract, proxy, stockage fichiers / docx). La policy (qui peut appeler quoi, sur quel chemin) reste du ressort du policy-runtime et du gateway. Local Office suit la même logique ; le schéma d’auth diffère (X-API-Key vs Authorization: Bearer pour les autres lignes du tableau).

Vue logique monorepo (extraits)

flowchart TB
  subgraph monorepo ["smart_ide monorepo"]
    docs[docs]
    svc[services]
    coreIde[core_ide]
    ia[ia_dev_module]
    ext[extensions]
    scr[scripts_setup_systemd]
  end
  subgraph svcDetail [services_detail]
    rds[repos-devtools-server]
    le[langextract-api]
    rg[agent-regex-search-api]
    ch[claw-harness-api]
    lo[local-office]
    iagw[ia-dev-gateway]
  end
  svc --> svcDetail
  gateway[agent_gateway_HTTP]
  orch[orchestrator_HTTP]
  gateway --> svcDetail
  gateway --> iagw
  orch --> gateway
  orch --> lo
  orch --> iagw
  coreIde --> editor[editor-shell_Lapce_build]

Un service navigateur embarqué (Chromium / Playwright) n’est pas requis par défaut ; critères d’introduction : features/browser-automation-criteria.md.

Socle applicatif : Lapce (core_ide/)

Les sources de Lapce vivent sous core_ide/ (clone de l’amont public, Apache-2.0) — socle applicatif de l’IDE. Le binaire ou paquet installé pour l’utilisateur est produit par build local à partir de cet arbre (ou livré par paquet système, selon politique d’équipe). Clone, mise à jour et build : core-ide.md. La personnalisation UX (intentions, appels aux micro-services) se fait dans la couche editor-shell / orchestrateur et n’impose pas un second dépôt produit. Portage de l’extension VS Code AnythingLLM vers Lapce : features/lapce-porting-roadmap.md.

UX — masquage des agents

L’utilisateur ne « choisit pas un agent » dans le flux nominal : il exprime une intention (ask, fix, …). Le routeur sélectionne l’agent ou la chaîne d’agents.

Taxonomie des droits

Les droits doivent être nommés, vérifiables et traçables (lien avec OpenShell et le registre d’agents). Pas de contournement par défaut.

Mémoire d’exécution

Conserver une mémoire d’exécution exploitable : rejouer, auditer, promouvoir une exécution réussie en recette versionnée.