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, API/README.md et 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. Configuration agrégée : 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
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)
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

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

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).

6. Rôles respectifs (rappel)

• IDE : orchestrateur (intentions), tools-bridge (registre + jobs outils), devtools AnythingLLM, repos-devtools, regex search, gateway, 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).

Voir aussi

• config/services.local.env.example
• repo/service-smart-ide-tools-bridge.md
• platform-target.md
• deployment-target.md