smart_ide/docs/ecosystem-architecture-and-sync.md

Architecture cible : smart_ide, projets développés, API IA et hôte

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, platform-target.md, anythingllm-workspaces.md, features/orchestrator-api.md, features/ia-dev-service.md, API/README.md, projects/README.md, features/docv-ai-integration.md.

1. Périmètres et référentiels

Élément	Rôle	Où vit la vérité opérationnelle
smart_ide	Socle : doc, services/*, scripts, systemd, confs ia_dev (./projects/<id>/conf.json), sous-module ia_dev/	Dépôt Git smart_ide (forge interne)
Projets développés	Code métier (docv, autres produits) : sources, builds, tests	Autres dépôts Git ; clones sur disque en dehors de ./projects/ (convention : répertoire frère ../projects/<nom>/ ou équivalent)
Couche API IA	Routage HTTP, auth, appels vers LLM, RAG, outils, agents	Processus sur l’hôte (systemd, ports locaux) ; contrats décrits sous docs/API/
Git (hôte)	Historique des dépôts, hooks, branches par environnement	Chaque dépôt ; politique de branche documentée par projet
Ollama (hôte)	Inférence locale (modèles)	Service sur l’hôte qui exécute l’inférence ; pas de duplication d’historique Git
AnythingLLM (hôte)	Workspaces RAG par projet, threads, documents indexés	Instance Docker ou service ; données persistées côté hôte ; pas substitut à Git pour le code source

La mémoire RAG (AnythingLLM) est une vue dérivée des fichiers autorisés du dépôt : elle doit suivre des règles d’inclusion / exclusion explicites (ex. .4nkaiignore), alignées avec la sécurité.

2. Schéma logique des flux

flowchart TB
  subgraph repos [Dépôts Git]
    SI[smart_ide]
    P1[projet_A_clone]
    P2[projet_B_clone]
  end
  subgraph host [Hôte]
    Git[Git_cli_hooks]
    Oll[Ollama]
    ALLM[AnythingLLM]
  end
  subgraph api [Couche API IA smart_ide]
    Orch[orchestrator]
    GW[ia_dev_gateway]
    MS[micro_services]
  end
  SI --> Git
  P1 --> Git
  P2 --> Git
  Orch --> Oll
  Orch --> ALLM
  Orch --> GW
  Orch --> MS
  GW --> SI
  Clients[IDE_docv_autres] --> Orch

• Les clients (Lapce, front, backend docv, scripts) parlent à l’orchestrateur et aux services exposés selon API/README.md.
• L’orchestrateur route vers Ollama (génération), AnythingLLM (RAG / contexte documentaire), ia-dev-gateway (agents / exécutions ia_dev), et les micro-services (langextract-api, agent-regex-search-api, repos-devtools-server, etc.) selon l’intention.
• Git relie les dépôts au disque ; les hooks et scripts assument la propagation contrôlée vers AnythingLLM après changements validés dans l’historique.

3. Rôle de chaque brique hôte

Git

• Source de vérité pour le code et la documentation versionnée des projets.
• Branches : alignement avec les environnements (test / pprod / prod) selon la politique du projet ; smart_ide documente les cibles dans platform-target.md et deployment-target.md.
• Sous-module ia_dev : git submodule update --init --recursive sur smart_ide ; puis scripts de post-checkout documentés (ia_dev-submodule.md, projects/README.md).

Ollama

• Point d’entrée pour les modèles consommés par l’orchestrateur, le gateway ou les outils ; configuration hôte (Docker ou natif) : services.md.
• Aucune synchronisation automatique implicite avec les dépôts : seuls les artefacts modèle (pull Ollama) sont gérés côté Ollama.

AnythingLLM

• Un workspace par projet logique : anythingllm-workspaces.md.
• Le workspace doit être alimenté à partir des clones autorisés ; si workspace ou clone manque, la procédure est : cloner / mettre à jour le dépôt, créer ou rattacher le workspace, lancer une synchro (voir § 4).

Outillage Git HTTP (repos-devtools-server)

• Clone et rafraîchissement de dépôts dans une racine contrôlée (REPOS_DEVTOOLS_ROOT) : complément à Git en ligne de commande pour l’IDE ou l’automation ; détail : API/repos-devtools-server.md.

4. Stratégie d’automatisation et de synchronisation

Objectif : après un changement tracé dans Git, les systèmes en aval (AnythingLLM, résolution ia_dev) restent cohérents sans copie manuelle ad hoc, dans la limite des outils actuels.

4.1 Ordre de référence (nouvelle machine ou post-clone)

1. Cloner smart_ide avec sous-modules : git clone --recurse-submodules ….
2. Initialiser / mettre à jour ia_dev : git submodule update --init --recursive.
3. Recréer le lien conf projet : ./scripts/ensure-ia-dev-smart-ide-project-link.sh (projects/README.md).
4. Cloner les projets applicatifs à l’emplacement convenu (ex. ../projects/<id>/) et vérifier les chemins absolus dans projects/<id>/conf.json si ia_dev doit les piloter.
5. Démarrer Ollama et AnythingLLM sur l’hôte (services.md) ; créer les workspaces et noter les slugs.
6. Configurer l’environnement de synchro AnythingLLM : ~/.config/4nk/anythingllm-sync.env (URL, clé API) — ne pas commiter les secrets.
7. Par dépôt à indexer : fichier .anythingllm.json à la racine avec { "workspaceSlug": "…" } (ou variable d’environnement équivalente), puis installer le hook post-merge : features/anythingllm-pull-sync-after-pull.md, scripts/anythingllm-pull-sync/README.md.

4.2 Cycle de travail développeur (projet applicatif)

1. git pull (ou merge) sur le clone du projet.
2. Le hook post-merge exécute scripts/anythingllm-pull-sync/sync.mjs : envoi des fichiers modifiés ou ajoutés vers le workspace AnythingLLM du projet, avec exclusions .4nkaiignore.
3. Limites documentées : pas de suppression automatique des documents retirés du repo dans la version actuelle du script ; traiter les gros refactors par une resynchro manuelle ou évolution du script si le besoin est récurrent.

4.3 Cycle de travail sur smart_ide

1. git pull sur smart_ide ; mettre à jour le sous-module ia_dev si le pointeur parent a bougé.
2. Réexécuter ensure-ia-dev-smart-ide-project-link.sh si le répertoire ia_dev/projects/ a été réinitialisé.
3. Option : installer le même hook post-merge sur le dépôt smart_ide si un workspace AnythingLLM est dédié au monorepo (fichier .anythingllm.json + slug).

4.4 Agents, déploiement, ticketing (ia_dev)

• Exécution depuis la racine du sous-module ia_dev/ ; résolution du projet : IA_PROJECT_ID, --project, MAIL_TO, AI_AGENT_TOKEN — voir ia_dev/projects/README.md dans le sous-module.
• Les scripts ne remplacent pas Git : ils lisent conf.json pour savoir où sont les dépôts et comment déployer.

4.5 Cohérence « clone présent + workspace aligné »

Situation	Action
Clone absent	git clone (ou API repos-devtools-server si périmètre autorisé) vers la racine convenue ; mettre à jour project_path dans conf.json si le chemin change (validation humaine pour toute modification de conf).
Workspace AnythingLLM absent	Créer le workspace dans l’UI ou l’API AnythingLLM ; renseigner .anythingllm.json ou ANYTHINGLLM_WORKSPACE_SLUG.
Workspace désynchronisé	git pull sur le clone concerné pour déclencher le hook ; ou exécuter manuellement sync.mjs avec les bons répertoires / variables.
Nouveau fichier sensible dans le dépôt	Vérifier .4nkaiignore avant le prochain upload ; ne pas indexer de secrets.

5. Intégrations tierces (ex. docv)

Le backend docv consomme la même couche API IA et les mêmes principes de projet = clone Git + workspace : features/docv-ai-integration.md. L’OIDC (SSO) est orthogonal aux flux de synchro fichier : features/sso-docv-enso.md.

6. Non-objectifs explicites dans cette stratégie

• Remplacer Git par AnythingLLM comme source du code.
• Synchroniser automatiquement sans hook ni script explicite : toute automatisation repose sur des mécanismes nommés (hooks, scripts du repo, systemd).
• Étendre le périmètre des dépôts sans contrôle de racine (REPOS_DEVTOOLS_ROOT, politique SSH) : hors sujet de ce document ; à traiter au niveau policy / OpenShell (system-architecture.md).