From f482b0e2b87a637721defe05d2f9b1bbbb48f350 Mon Sep 17 00:00:00 2001 From: 4NK Date: Fri, 3 Apr 2026 22:37:31 +0200 Subject: [PATCH] docs: services functional scope for IDE vs product backends - Add services-functional-scope.md with consumption matrix and CLI tools - Cross-link from services, API index, architecture, platform-target, ecosystem, docv-ai, overview --- docs/API/README.md | 2 + docs/README.md | 3 +- docs/ecosystem-architecture-and-sync.md | 2 +- docs/features/docv-ai-integration.md | 2 + docs/platform-target.md | 2 +- docs/repo/smart-ide-overview.md | 1 + docs/services-functional-scope.md | 64 +++++++++++++++++++++++++ docs/services.md | 2 + docs/system-architecture.md | 2 +- 9 files changed, 76 insertions(+), 4 deletions(-) create mode 100644 docs/services-functional-scope.md diff --git a/docs/API/README.md b/docs/API/README.md index 6015c90..0a72f0c 100644 --- a/docs/API/README.md +++ b/docs/API/README.md @@ -2,6 +2,8 @@ Documentation des **API HTTP** exposées par les services sous [`services/`](../../services/). Chaque service écoute en principe sur **`127.0.0.1`** ; ports et variables d’environnement sont rappelés par fiche. +**Périmètre fonctionnel et consommation** (IDE, automation, backends produit) : [services-functional-scope.md](../services-functional-scope.md). + | Service | Auth | Port défaut | Fiche | |---------|------|-------------|--------| | **repos-devtools-server** | `Authorization: Bearer` | `37140` | [repos-devtools-server.md](./repos-devtools-server.md) | diff --git a/docs/README.md b/docs/README.md index 0e83da4..e7ec65b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,6 +42,7 @@ Les fichiers **`README.md`** sous `services/*/`, `cron/`, `projects/`, etc. ne f | Document | Contenu | |----------|---------| +| [services-functional-scope.md](./services-functional-scope.md) | Périmètre fonctionnel des services, rôle **IDE** vs **backends applicatifs** | | [platform-target.md](./platform-target.md) | Vision plateforme en ligne, 3 envs, machine IA unique vs SSH, SSO, navigateur optionnel | | [implementation-rollout.md](./implementation-rollout.md) | Déroulé du plan plateforme : doc + code minimal, suites | | [system-architecture.md](./system-architecture.md) | Couches, monorepo, cartographie des dossiers, gateway, OpenShell, micro-services | @@ -49,7 +50,7 @@ Les fichiers **`README.md`** sous `services/*/`, `cron/`, `projects/`, etc. ne f | [core-ide.md](./core-ide.md) | Socle applicatif Lapce : `core_ide/`, clone amont, build | | [deployment-target.md](./deployment-target.md) | Client Linux + SSH, variante machine IA unique, serveur socle IA et repos | | [infrastructure.md](./infrastructure.md) | SSH, accès hôte, renvois vers les scripts | -| [services.md](./services.md) | Ollama, AnythingLLM, **Local Office**, micro-services HTTP sous `services/` | +| [services.md](./services.md) | Ollama, AnythingLLM, **Local Office**, micro-services HTTP ; renvoie vers la vue fonctionnelle détaillée | ## Référence API des services (`API/`) diff --git a/docs/ecosystem-architecture-and-sync.md b/docs/ecosystem-architecture-and-sync.md index ca57716..955e205 100644 --- a/docs/ecosystem-architecture-and-sync.md +++ b/docs/ecosystem-architecture-and-sync.md @@ -2,7 +2,7 @@ Ce document fixe la **répartition souhaitée** entre le monorepo **smart_ide**, les **dépôts applicatifs** développés ailleurs, la **couche API IA** (orchestrateur, gateway, micro-services HTTP), et les **services d’hôte** (**Git**, **Ollama**, **AnythingLLM**). Il décrit ensuite une **stratégie d’automatisation et de synchronisation** cohérente, centrée sur **Git** et des **scripts** du dépôt smart_ide. -Références complémentaires : [system-architecture.md](./system-architecture.md), [platform-target.md](./platform-target.md), [anythingllm-workspaces.md](./anythingllm-workspaces.md), [features/orchestrator-api.md](./features/orchestrator-api.md), [features/ia-dev-service.md](./features/ia-dev-service.md), [API/README.md](./API/README.md), [repo/projects-directory.md](./repo/projects-directory.md), [features/docv-ai-integration.md](./features/docv-ai-integration.md), [features/docv-service-integration.md](./features/docv-service-integration.md). +Références complémentaires : [services-functional-scope.md](./services-functional-scope.md) (périmètres IDE / backends), [system-architecture.md](./system-architecture.md), [platform-target.md](./platform-target.md), [anythingllm-workspaces.md](./anythingllm-workspaces.md), [features/orchestrator-api.md](./features/orchestrator-api.md), [features/ia-dev-service.md](./features/ia-dev-service.md), [API/README.md](./API/README.md), [repo/projects-directory.md](./repo/projects-directory.md), [features/docv-ai-integration.md](./features/docv-ai-integration.md), [features/docv-service-integration.md](./features/docv-service-integration.md). ## 1. Périmètres et référentiels diff --git a/docs/features/docv-ai-integration.md b/docs/features/docv-ai-integration.md index 2e3a69b..7a269be 100644 --- a/docs/features/docv-ai-integration.md +++ b/docs/features/docv-ai-integration.md @@ -6,6 +6,8 @@ Le monorepo **smart_ide** sert aussi de **socle technique** pour les intégrations IA consommées par le **backend docv** (filière Enso). Le principe : exposer, parmi les services locaux, des **API HTTP génériques** (orchestrateur, gateway agents, Ollama, AnythingLLM, micro-services sous `services/`) que le back **docv** peut appeler pour offrir les fonctionnalités IA **par projet**. +Quels services privilégier côté back (et lesquels restent orientés poste IDE) : **[services-functional-scope.md](../services-functional-scope.md)** § 2 et § 4. + Référence d’arborescence côté Enso (machine de développement type) : dépôt **docv** sous un chemin du genre `…/enso/docv` (ex. historique `/home/desk/code/enso/docv`). Les URLs et secrets réels par environnement restent hors dépôt ([platform-target.md](../platform-target.md), [sso-docv-enso.md](./sso-docv-enso.md)). ## Modèle « projet » diff --git a/docs/platform-target.md b/docs/platform-target.md index ef4a29a..6924688 100644 --- a/docs/platform-target.md +++ b/docs/platform-target.md @@ -45,7 +45,7 @@ Le **front web** de la plateforme peut s’authentifier auprès de **docv** (fil ## API IA pour le backend docv -Le monorepo expose des **services HTTP génériques** (orchestrateur, gateway, RAG, inférence) que le **back docv** peut consommer **par projet** ; clones Git et workspaces AnythingLLM doivent exister et être tenus à jour. Détail : [features/docv-ai-integration.md](./features/docv-ai-integration.md). +Le monorepo expose des **services HTTP génériques** (orchestrateur, gateway, RAG, inférence) que le **back docv** peut consommer **par projet** ; clones Git et workspaces AnythingLLM doivent exister et être tenus à jour. Détail : [features/docv-ai-integration.md](./features/docv-ai-integration.md). Tableau des périmètres et arbitrages IDE / backends : [services-functional-scope.md](./services-functional-scope.md). ## Chaîne technique de référence diff --git a/docs/repo/smart-ide-overview.md b/docs/repo/smart-ide-overview.md index 25bb384..2330287 100644 --- a/docs/repo/smart-ide-overview.md +++ b/docs/repo/smart-ide-overview.md @@ -42,6 +42,7 @@ Le répertoire **`ia_dev/`** contient l’**équipe d’agents**, les scripts `d | Référence HTTP services | [API/README.md](../API/README.md) | | Infra SSH / scripts hôte | [infrastructure.md](../infrastructure.md) | | Ollama, AnythingLLM, services | [services.md](../services.md) | +| Périmètres IDE / backends applicatifs | [services-functional-scope.md](../services-functional-scope.md) | | UX / intentions | [ux-navigation-model.md](../ux-navigation-model.md) | | Écosystème et synchro | [ecosystem-architecture-and-sync.md](../ecosystem-architecture-and-sync.md) | | Projets `conf.json` | [projects-directory.md](./projects-directory.md) | diff --git a/docs/services-functional-scope.md b/docs/services-functional-scope.md new file mode 100644 index 0000000..cbd3bdc --- /dev/null +++ b/docs/services-functional-scope.md @@ -0,0 +1,64 @@ +# 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 | + +## 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//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, 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](./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) +- [platform-target.md](./platform-target.md) +- [deployment-target.md](./deployment-target.md) diff --git a/docs/services.md b/docs/services.md index 3db8d39..852911c 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,5 +1,7 @@ # Services sur l’hôte (socle technique) +**Vue fonctionnelle détaillée** (périmètre de chaque service, usage **IDE** vs **backends applicatifs** des projets) : **[services-functional-scope.md](./services-functional-scope.md)**. + Ce document décrit les **services logiciels** typiques sur l’**hôte** (serveur distant **ou** machine IA unique — voir [deployment-target.md](./deployment-target.md) et [platform-target.md](./platform-target.md)), en complément de [system-architecture.md](./system-architecture.md). **Ollama** et **AnythingLLM** peuvent cohabiter sur le même hôte que les micro-services ; l’**orchestrateur** HTTP ([features/orchestrator-api.md](./features/orchestrator-api.md)) et **`ia-dev-gateway`** ([features/ia-dev-service.md](./features/ia-dev-service.md)) sont spécifiés pour unifier les appels depuis Lapce ou le front. ## Ollama diff --git a/docs/system-architecture.md b/docs/system-architecture.md index 3c60113..05ad9c9 100644 --- a/docs/system-architecture.md +++ b/docs/system-architecture.md @@ -1,6 +1,6 @@ # 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). +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). **Rôles fonctionnels des services** (IDE vs backends applicatifs) : [services-functional-scope.md](./services-functional-scope.md). ## Objectifs du projet (rappel)