chlova/CLAUDE.md

CHLOVA — guide projet (CLAUDE.md)

CHLOVA est un assistant personnel (inspiré de Jarvis). Ce n'est pas un produit from-scratch : c'est une couche d'orchestration au-dessus d'un homelab existant. Le cerveau est un LLM en boucle tool-calling : comprendre → choisir un outil MCP → agir → observer → répondre.

Substrat existant (réutiliser, ne pas réinventer)

• Debian + Docker + Traefik.
• n8n (automations) — joignable via son MCP.
• Portainer (déploiement de conteneurs) — joignable via son MCP.
• Ollama : conteneur de la stack, joignable par l'orchestrateur sur le réseau Docker interne (http://ollama:11434). On utilise des modèles cloud (suffixe :cloud) : le conteneur Ollama local agit en proxy authentifié vers l'infra distante d'Ollama. Transparent pour l'orchestrateur (il croit parler à du Ollama local). Auth via OLLAMA_API_KEY (coffre, jamais en dur). Conséquences : pas de GPU requis, mais les requêtes sortent vers ollama.com (egress doit l'autoriser) et il n'existe pas de palier "local/privé".

Architecture cible

• Tout vit sur le serveur : orchestrateur LLM + Ollama (proxy cloud) + outils MCP.
• Une seule surface exposée : le backend CHLOVA. Lui seul contacte Ollama, n8n et Portainer, sur le réseau Docker interne. Aucune brique interne n'est jamais joignable directement de l'extérieur.
• Le mobile est un client léger du backend CHLOVA, rien d'autre.
• Outils MCP : MCP n8n + MCP Portainer.
• Surfaces : texte d'abord (Telegram/Signal = nativement mobile, sans exposition), voix ensuite (STT + wake-word + TTS). La voix vient après un cerveau fiable.
• Auto-extension : si une demande n'est pas réalisable avec les outils existants, CHLOVA les crée lui-même en état "need review".

Stack retenue (Phases 0–1)

• Orchestrateur : TypeScript + Node 22, MCP SDK officiel @modelcontextprotocol/sdk (client).
• Backend/API : Fastify.
• LLM : client Ollama /api/chat (tool-calling natif), modèles :cloud.
• Surface texte Phase 1 : bot Telegram (long-polling → zéro port ouvert).
• MCP : n8n natif (instance ≥ 2.18.4, pas de conteneur — endpoint MCP servi par n8n, à activer) + Portainer sidecar portainer/portainer-mcp (tag épinglé). Read-only en Phase 1.
• Tests : Vitest (gatekeeper + scoping read-only).
• État assets : SQLite (table posée dès P0/P1, câblée en P2+).

Versioning & documentation (non négociable)

Git est la source unique de vérité. Tout artefact créé/modifié — workflow n8n, stack/compose Docker, code orchestrateur, outil — doit être :

• Versionné : commit dédié + semver (vMAJEUR.MINEUR.PATCH). Chaque création/modif = un commit clair + bump. CHANGELOG.md tenu à jour.
• Documenté : rôle, entrées/sorties, dépendances, palier de risque, rollback. Un artefact non documenté est incomplet.
• Images Docker : tags épinglés et versionnés (jamais :latest).
• Workflows n8n : exportés en JSON dans workflows-n8n/ (le dépôt fait foi).

Rien n'est "terminé" tant qu'il n'est pas à la fois versionné ET documenté.

Accès mobile & exposition (non négociable)

• Seul le backend CHLOVA est exposé, derrière auth + TLS.
• Voie mobile : surface Telegram/Signal (distante par nature, zéro port ouvert) ET/OU VPN mesh (Tailscale/Wireguard) + Traefik/TLS pour une API/UI CHLOVA.
• Ollama, n8n, Portainer n'écoutent que sur le réseau Docker interne. Ollama n'a aucune auth native — ne jamais l'exposer.

Paliers de risque (règle non négociable)

• Réversible / lecture seule → 7 jours de sursis PROVISOIRE autorisés.
• Privilégié / destructeur → aucun sursis : BLOQUÉ jusqu'à review. (déploiement Portainer, montage de volume hôte, accès secrets, suppression, exec dans un conteneur, etc.)
• Le LLM ne doit jamais pouvoir reclasser un asset privilégié en réversible.

Cycle de vie "need review" (Phase 2+, interfaces posées en P1)

États d'un asset créé par CHLOVA : PROVISOIRE (7 j) → APPROUVÉ / REFUSÉ / BLOQUÉ. Table assets : id, type, version, palier_risque, statut, created_at, expires_at, exec_count, lien_commit, lien_doc. Cron horaire PROVISOIRE→BLOQUÉ ; gatekeeper qui vérifie le statut avant chaque exécution.

Sécurité (non négociable — risque n°1 : prompt injection)

• Accès quasi-root via Portainer : socket-proxy Docker obligatoire, tokens Portainer/n8n à portée restreinte, réseau dédié à l'agent, egress filtré (autoriser ollama.com).
• L'agent ne voit jamais les secrets en clair : il manipule des références. Tous les secrets via env/coffre, jamais en dur ; .env.example fourni.
• Toute opération mutante est audit-loggée.
• Déploiements de stacks en GitOps quand possible (rollback + audit gratuits).

Périmètre actuel

• Phase 0 : socle (structure, CLAUDE.md, config, sécurité, conventions, docker-compose stack avec Ollama interne + backend seule surface).
• Phase 1 : cerveau lecture seule (orchestrateur LLM via Ollama cloud + MCP n8n + MCP Portainer read-only + surface texte).
• Phases 2+ NON implémentées ici : écriture, need-review, voix, auto-extension. On pose seulement les interfaces/abstractions.