docs: conventions versioning + doc + paliers de risque (v0.2.0)

Pose les règles non négociables : SemVer + un-artefact-un-commit, pinning des images, export JSON des workflows n8n ; gabarit de doc d'asset ; paliers réversible/privilégié avec invariant anti-escalade ; schéma d'architecture et invariants d'exposition. Ignore settings.local.json. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-23 00:59:25 +02:00
parent a301281594
commit c096fa9467
6 changed files with 198 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Architecture CHLOVA
+
+> Vue d'ensemble. Les règles non négociables font foi dans `CLAUDE.md`.
+
+## Principe
+CHLOVA est une **couche d'orchestration** : un LLM en boucle tool-calling
+(`comprendre → choisir un outil MCP → agir → observer → répondre`) posée au-dessus
+d'un homelab Debian + Docker + Traefik existant.
+
+## Schéma logique
+```
+        mobile (client léger)
+              │  Telegram (long-polling, zéro port ouvert)
+              ▼
+   ┌─────────────────────────┐        réseau Docker interne (chlova-internal)
+   │   Backend CHLOVA        │   ─────────────────────────────────────────────
+   │  (seule surface exposée)│        ┌───────────┐   ┌──────────────┐
+   │   - boucle agent        │ ─────► │  Ollama   │ ─►│ ollama.com    │ (egress)
+   │   - registry MCP        │        │ (proxy    │   │ modèles :cloud│
+   │   - gatekeeper (P2+)    │        │  cloud)   │   └──────────────┘
+   │   - audit log           │        └───────────┘
+   └─────────────────────────┘
+        │ MCP (stdio/http interne)
+        ├───────────────► MCP n8n  ──► n8n API (interne)
+        └───────────────► MCP Portainer ─► socket-proxy ─► Docker / Portainer
+```
+
+## Invariants
+- **Une seule surface exposée** : le backend CHLOVA (auth + TLS). Tout le reste
+  (Ollama, n8n, Portainer, serveurs MCP) n'écoute **que** sur `chlova-internal`.
+- **Ollama sans auth native** → jamais exposé ; il sort vers `ollama.com` pour les
+  modèles `:cloud` (egress filtré, seul `ollama.com` autorisé).
+- **Accès Docker via socket-proxy** uniquement (pas de socket brut dans l'agent).
+- **Secrets par référence** : l'agent ne voit jamais les valeurs en clair.
+
+## Boucle agent (Phase 1, lecture seule)
+1. Message texte (Telegram) → backend.
+2. Backend appelle Ollama `/api/chat` avec la liste d'outils MCP **read-only**.
+3. Le modèle choisit un outil → le backend l'exécute via le serveur MCP.
+4. Observation renvoyée au modèle → réponse finale → utilisateur.
+5. Toute exécution d'outil est **audit-loggée**.
+
+En Phase 1, le **readonly-filter** garantit que seuls les outils `readOnlyHint=true`
+sont exposés : aucun risque d'écriture.
+
+## Évolutions (interfaces posées, non implémentées)
+- **Gatekeeper + table assets** : vérifie le statut avant chaque exécution (P2).
+- **Cycle need-review** : PROVISOIRE → APPROUVÉ/REFUSÉ/BLOQUÉ + cron horaire (P2).
+- **Auto-extension** : création d'outils/workflows en "need review" (P4).
+- **Voix** : STT + wake-word + TTS (P5), après un cerveau fiable.
+
+## Composants & contrats
+| Composant | Image / lib | Exposition | Palier |
+|---|---|---|---|
+| Backend CHLOVA | code maison (TS) | seule surface | — |
+| Ollama (proxy cloud) | `ollama/ollama` épinglé | interne | — |
+| MCP n8n | `czlonkowski/n8n-mcp` épinglé | interne | read-only (P1) |
+| MCP Portainer | `portainer/portainer-mcp` épinglé | interne | read-only (P1) |
+| socket-proxy | `tecnativa/docker-socket-proxy` épinglé | interne | scoping Docker |