# 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 natif (endpoint sur l'instance n8n, interne)
        └───────────────► MCP Portainer (sidecar) ─► 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 | **natif** dans n8n ≥ 2.18.4 (pas de conteneur) | interne | read-only (P1) |
| MCP Portainer | `portainer/portainer-mcp` épinglé (sidecar) | interne | read-only (P1) |
| socket-proxy | `tecnativa/docker-socket-proxy` épinglé | interne | scoping Docker |