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](./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), [projects/README.md](../projects/README.md), [features/docv-ai-integration.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

```mermaid
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](./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](./platform-target.md) et [deployment-target.md](./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](./ia_dev-submodule.md), [projects/README.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](./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](./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](./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](../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](./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](./features/anythingllm-pull-sync-after-pull.md), [scripts/anythingllm-pull-sync/README.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](./features/docv-ai-integration.md). L’**OIDC** (SSO) est orthogonal aux flux de synchro fichier : [features/sso-docv-enso.md](./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](./system-architecture.md)).