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](./platform-target.md). Architecture **écosystème + synchronisation** (projets externes, API IA, hôte) : [ecosystem-architecture-and-sync.md](./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](./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](./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](./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](./deployment-target.md). Les déploiements **test / pprod / prod** : [platform-target.md](./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](./core-ide.md).
- `ia_dev` est un **répertoire versionné** dans ce monorepo (évolution historique depuis le dépôt forge [4nk/ia_dev](https://git.4nkweb.com/4nk/ia_dev.git)) ; intégration et journaux : [ia_dev-module.md](./ia_dev-module.md), [repo/ia-dev-smart-ide-integration.md](./repo/ia-dev-smart-ide-integration.md), [repo/logs-directory.md](./repo/logs-directory.md). Un service HTTP **`ia-dev-gateway`** ([features/ia-dev-service.md](./features/ia-dev-service.md)) exposera le registre et les exécutions agents.
- **Orchestrateur** HTTP : [features/orchestrator-api.md](./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](./API/anythingllm-devtools-api.md) |
| `services/carbonyl/` | Navigateur terminal Chromium ([Carbonyl](https://github.com/fathyb/carbonyl)) ; sous-module **`upstream/`** ; prévisualisation test — [repo/service-carbonyl.md](./repo/service-carbonyl.md) |
| `services/pageindex/` | Index sémantique arborescent PDF/MD ([PageIndex](https://github.com/VectifyAI/PageIndex)) ; sous-module **`upstream/`** ; CLI — [repo/service-pageindex.md](./repo/service-pageindex.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](./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](./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](./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](./ia_dev-module.md) |
| `services/ia-dev-gateway/` | Gateway HTTP (stub runner) : registre agents `.md`, runs, SSE — [features/ia-dev-service.md](./features/ia-dev-service.md) |
| `services/smart-ide-orchestrator/` | Routage intentions (stub forward) — [features/orchestrator-api.md](./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](./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](https://git.4nkweb.com/4nk/ia_dev.git) 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](./ia_dev-module.md) et [repo/ia-dev-smart-ide-integration.md](./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](./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](./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](./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](./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](./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](./repo/service-repos-devtools.md) |
| **langextract-api** | Extraction structurée depuis texte (wrapper [LangExtract](https://github.com/google/langextract)) | [features/langextract-api.md](./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](./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](./features/agent-regex-search-api.md) |
| **local-office** | API REST Office : upload, commandes docx ; auth **`X-API-Key`** (pas Bearer) | [features/local-office.md](./features/local-office.md) , [repo/service-local-office.md](./repo/service-local-office.md) |
| **ia-dev-gateway** | Registre agents, runs stub, flux SSE (Node/TS) | [features/ia-dev-service.md](./features/ia-dev-service.md) , [API/ia-dev-gateway.md](./API/ia-dev-gateway.md) , [repo/service-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](./features/orchestrator-api.md) , [API/orchestrator.md](./API/orchestrator.md) , [repo/service-smart-ide-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)

```mermaid
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](./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](./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](./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.