smart_ide/docs/services-functional-scope.md

# Périmètre fonctionnel des services — IDE, plateforme et backends applicatifs

Ce document précise **ce que fait chaque brique** (fonction métier / technique), **qui l’utilise** (IDE, automation, backend d’un produit), et **ce qui est hors périmètre**. Il complète [services.md](./services.md), [API/README.md](./API/README.md) et [ecosystem-architecture-and-sync.md](./ecosystem-architecture-and-sync.md).

## 1. Trois contextes de consommation

| Contexte | Acteur typique | Objectif |
|----------|----------------|----------|
| **IDE / poste développeur** | Lapce, Cursor, scripts locaux, extensions | Édition, Git, agents, prévisualisation, découverte des endpoints, tâches documentaires ponctuelles |
| **Automation / ia_dev** | `ia_dev`, cron, hooks, CI autorisée | Déploiement, tickets, synchro RAG, clones sous racine contrôlée |
| **Backend applicatif (projet développé)** | Serveur **docv**, API **Enso**, autres produits 4NK | Fonctionnalités **métier** exposées aux utilisateurs finaux ; appels **serveur à serveur** vers la couche IA générique si le produit le prévoit |

**Règle de séparation** : les micro-services sous `services/` du monorepo **smart_ide** sont une **plateforme technique** (outillage, IA générique, orchestration). Les **API REST métier** (gestion documentaire, règles métier, persistance produit) vivent dans les **dépôts applicatifs** (ex. **docv**), pas dans smart_ide.

## 2. Services HTTP du monorepo `smart_ide`

Tous écoutent en principe sur **`127.0.0.1`** ; ports par défaut : [API/README.md](./API/README.md). Configuration agrégée : [config/services.local.env.example](../config/services.local.env.example).

| Service | Périmètre fonctionnel | Rôle pour l’**IDE** | Rôle pour les **backends applicatifs** (projets) |
|---------|------------------------|---------------------|---------------------------------------------------|
| **smart_ide-orchestrator** | Résolution d’**intentions** en cibles (Ollama, AnythingLLM, micro-services, gateway) sans logique LLM propre | Point d’entrée unique pour l’UI « intentions » ; `dryRun` pour inspection | **Optionnel** : même point d’entrée si le back route par intention ; sinon appels **directs** aux services cibles pour moins d’indirection |
| **ia-dev-gateway** | Registre d’**agents** `ia_dev`, lancement de **runs**, flux SSE (spécification) | Palette / outils « lancer agent », timeline | **Possible** pour scénarios « agent long » déclenchés depuis un back ; contrat : [features/ia-dev-service.md](./features/ia-dev-service.md) |
| **repos-devtools-server** | **Clone / liste / chargement** de dépôts Git sous une racine contrôlée (`REPOS_DEVTOOLS_ROOT`) | Rafraîchir l’espace de code sans quitter l’IDE | **Rarement** côté prod utilisateur ; plutôt **outillage** et environnements de build / sandbox |
| **anythingllm-devtools** | **Workspaces AnythingLLM**, upload documentaire, orchestration avec repos-devtools, **RAG initial** (`.4nkaiignore`) | Aligner workspace / dépôt depuis l’IDE ou un script | **Possible** pour pipelines « alimenter le RAG » automatisés ; secrets et URL AnythingLLM côté hôte |
| **langextract-api** | **Extraction structurée** depuis texte (schéma, exemples, modèle configurable) | Enrichir une feature « extraire des entités » dans l’IDE | **Recommandé** comme brique générique quand le back a besoin d’extractions typées (voir [docv-ai-integration.md](./features/docv-ai-integration.md)) |
| **agent-regex-search-api** | **Recherche regex** sur fichiers (ripgrep), périmètre **`REGEX_SEARCH_ROOT`** | Recherche symbolique large dans le workspace | **Prudent** : exposer seulement si le root est **strictement** borné ; plutôt poste dev ou job batch |
| **claw-harness-api** (proxy) | **Proxy HTTP** vers un exécuteur claw-code amont | Outillage modèles alternatifs en dev | **Optionnel** si politique projet autorise ce proxy en interne |
| **local-office** | **Manipulation programmatique** de fichiers Office (docx, etc.), clé `X-API-Key` | Tests / génération de documents depuis l’IDE | **Possible** pour génération batch ou transformations Office côté serveur applicatif (hors UI ONLYOFFICE) |
| **smart-ide-tools-bridge** | **Registre** des URLs locales ; **jobs** Carbonyl / PageIndex / Chandra (chemins validés sous `SMART_IDE_MONOREPO_ROOT`) | Découverte des services ; lancer OCR / index / plan terminal depuis l’IDE | **Non prévu pour le trafic utilisateur final** : jobs longs, liés au poste / au monorepo ; les **backs produit** doivent préférer leurs propres pipelines (OCR, index) en prod si besoin |
| **smart-ide-sso-gateway** | **Validation JWT** docv / Enso + **proxy** via **smart-ide-global-api** vers les micro-services | Alternative au BFF maison pour un front ou un outil qui appelle déjà l’IdP | **Possible** quand le produit veut un seul point d’entrée HTTP local vers la plateforme IA sous identité utilisateur OIDC ; les appels M2M peuvent rester directs vers un micro-service ou vers l’API globale — [features/sso-gateway-service.md](./features/sso-gateway-service.md), [repo/service-smart-ide-global-api.md](./repo/service-smart-ide-global-api.md) |

## 3. Outils CLI et sous-modules (sans listener HTTP dédié)

| Outil | Périmètre fonctionnel | IDE | Backends applicatifs |
|-------|------------------------|-----|----------------------|
| **Carbonyl** (`services/carbonyl/`) | Navigateur **terminal** (Chromium) pour ouvrir une URL | Prévisualisation test (`preview_urls` + scripts) ; via bridge `open-plan` | Pas d’intégration serveur typique |
| **PageIndex** (`services/pageindex/`) | **Index arborescent** « vectorless » sur PDF / Markdown | Via **tools-bridge** `POST /v1/pageindex/run` | Réutiliser le **modèle** (amont) dans un pipeline produit si besoin ; pas le bridge comme API publique |
| **Chandra** (`services/chandra/`) | **OCR** structuré PDF / images → MD / HTML / JSON | Via **tools-bridge** `POST /v1/chandra/ocr` ou CLI locale | Même logique : **moteur** amont réutilisable ; le bridge reste **outil poste** |

## 4. Services d’hôte hors code `services/` (souvent Docker / systemd)

| Composant | Périmètre | IDE | Backends applicatifs |
|-----------|-----------|-----|----------------------|
| **Ollama** | Inférence **LLM** locale | Chat / complétion via orchestrateur ou URL directe | Appels HTTP **`/api/...`** depuis le back si réseau et politique le permettent |
| **AnythingLLM** | **RAG**, workspaces, threads | Consultation workspace, synchro via devtools / scripts | API workspace / documents pour **QA** ou recherche documentaire métier ([anythingllm-workspaces.md](./anythingllm-workspaces.md)) |
| **ONLYOFFICE** | Édition bureautique **interactive** | Intégration front | Embarqué côté produit pour l’utilisateur final |
| **docv** (dépôt **externe**) | **Gestion documentaire métier**, persistance, règles Enso | Consommation comme **produit** | C’est **l’API métier** documentaire ; elle peut **appeler** orchestrateur / Ollama / AnythingLLM / langextract selon [docv-ai-integration.md](./features/docv-ai-integration.md) |

## 5. API des projets développés (clarification)

- Les **backends** des projets (ex. **docv**, API **enso-front** / BFF, services métier) exposent leurs **propres** routes (REST, GraphQL, etc.) vers le **front** et les **clients**.
- Le monorepo **smart_ide** ne remplace **pas** ces API : il fournit des **micro-services transverses** et de la **documentation** (`projects/<id>/conf.json`, SSH, chemins données).
- Intégration type **docv → smart_ide** : serveur à serveur, tokens dédiés, réseau interne ; orthogonal au **SSO** utilisateur ([sso-docv-enso.md](./features/sso-docv-enso.md)).

## 6. Rôles respectifs (rappel)

- **IDE** : orchestrateur (intentions), tools-bridge (registre + jobs outils), devtools AnythingLLM, repos-devtools, regex search, ia-dev-gateway, **smart-ide-global-api** + **smart-ide-sso-gateway** (OIDC utilisateur → API globale → micro-services, si activé), accès directs Ollama / AnythingLLM selon l’UX.
- **Backends applicatifs** : consommer en priorité les services **stables et documentés** pour l’IA générique (**langextract**, **AnythingLLM**, **Ollama**, éventuellement **orchestrateur**) ; éviter de dépendre du **tools-bridge** pour la charge utilisateur ; respecter périmètres fichiers (`REGEX_SEARCH_ROOT`, SSH / données déployées — [remote-deployed-data-ssh.md](./features/remote-deployed-data-ssh.md)).

## Voir aussi

- [config/services.local.env.example](../config/services.local.env.example)  
- [repo/service-smart-ide-tools-bridge.md](./repo/service-smart-ide-tools-bridge.md)  
- [repo/service-smart-ide-global-api.md](./repo/service-smart-ide-global-api.md)  
- [repo/service-smart-ide-sso-gateway.md](./repo/service-smart-ide-sso-gateway.md)  
- [platform-target.md](./platform-target.md)  
- [deployment-target.md](./deployment-target.md)