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, features/docv-service-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), module ia_dev/, journaux logs/	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
  subgraph docv_layer [docv_externe]
    Docv[docv_HTTP]
    DataA["projects_A_data"]
    DataB["projects_B_data"]
  end
  SI --> Git
  P1 --> Git
  P2 --> Git
  P1 --> DataA
  P2 --> DataB
  Docv --> DataA
  Docv --> DataB
  Orch --> Oll
  Orch --> ALLM
  Orch --> GW
  Orch --> MS
  Orch --> Docv
  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.
• Module ia_dev : présent dans l’arborescence du dépôt smart_ide ; liens ia_dev/projects/* et scripts documentés (ia_dev-module.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 : git clone … (le répertoire ia_dev/ suit le même historique Git que le monorepo).
2. Recréer le lien conf projet si besoin : ./scripts/ensure-ia-dev-smart-ide-project-link.sh (projects/README.md).
3. 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.
4. Démarrer Ollama et AnythingLLM sur l’hôte (services.md) ; créer les workspaces et noter les slugs.
5. Configurer l’environnement de synchro AnythingLLM : ~/.config/4nk/anythingllm-sync.env (URL, clé API) — ne pas commiter les secrets.
6. 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 — peut être automatisé par cron/git-pull-project-clones.sh à partir des projects/<id>/conf.json (voir cron/README.md).
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 (inclut les mises à jour sous ia_dev/).
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 de ia_dev/ ; résolution du projet : IA_PROJECT_ID, --project, MAIL_TO, AI_AGENT_TOKEN — voir ia_dev/projects/README.md.
• 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 (docv)

• Gestion documentaire et données sous PROJECTS_CLONE_ROOT/<projet>/data/ (souvent ../projects/<projet>/data relatif à smart_ide) : features/docv-service-integration.md.
• API IA consommées par le backend docv (orchestrateur, Ollama, AnythingLLM, etc.) : features/docv-ai-integration.md.
• SSO OIDC : orthogonal aux flux fichiers et aux appels serveur à serveur : features/sso-docv-enso.md.

Sur un hôte distinct, docv résout DOCV_PROJECTS_ROOT localement ; smart_ide atteint docv via DOCV_BASE_URL — sans stockage partagé, les répertoires data/ ne sont pas les mêmes sur les deux machines.

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