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), [features/docv-service-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

```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
  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](./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).
- **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](./ia_dev-module.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** : `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](../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](./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](./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 — peut être **automatisé** par [`cron/git-pull-project-clones.sh`](../cron/git-pull-project-clones.sh) à partir des `projects/<id>/conf.json` (voir [`cron/README.md`](../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`](../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](./features/docv-service-integration.md).
- **API IA** consommées par le backend docv (orchestrateur, Ollama, AnythingLLM, etc.) : [features/docv-ai-integration.md](./features/docv-ai-integration.md).
- **SSO OIDC** : orthogonal aux flux fichiers et aux appels serveur à serveur : [features/sso-docv-enso.md](./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](./system-architecture.md)).