Telegram Orchestrator

1. Quoi ? — Définition et contexte

Le Telegram Orchestrator est le workflow N8N qui sert de point d’entrée pour toutes les interactions humaines avec l’infrastructure VPS. Il reçoit chaque message et chaque callback Telegram, vérifie l’authentification, route vers le bon handler, et délègue les tâches longues à 13 sub-workflows callback + 4 service handlers extraits.

Composants au plus haut niveau

Composant	Rôle
Telegram Bot	Interface utilisateur (messages, boutons inline, ForceReply)
IA Router	Détection d’intent via Claude (5 services : docker, n8n, odoo, content, general)
Command Router	Parsing `/menu`, `/docker`, `/n8n`, `/odoo`, `/help`, `/notif`, `/todo`, `/triage`, `/projet`, `/note`, `/blog`, `/research`, `/new`, `/conv`, `/endconv`, `/model`, `/plan`, `/templates`, `/mcp`
13 sub-workflows callback	Auth, menus, n8n actions, photos, conversations, file provider, etc.
4 service handlers	Docker, Odoo, N8N, General (chat Claude)
Binary Content Handler	Photos (via Vision OCR), notes vocales, vCard, PDF, vidéos
Conversation Agent + Plan Engine	Conversations multi-tours et plans d’action

Architecture visuelle

Les 21 commandes

Catégorie	Commandes
Menu	`/menu`, `/start`, `/docker`, `/n8n`, `/odoo`, `/help`, `/notif`, `/todo`, `/triage`
Contenu	`/note`, `/blog`, `/research`
Conversation	`/new`, `/conv`, `/endconv`, `/model`, `/plan`, `/templates`, `/mcp`
Projet	`/projet` (sous-commandes `list`, `create`, `status` avec picker paginé)

2. Pourquoi ? — Enjeux et motivations

Problèmes résolus

Problème	Sans orchestrator	Avec orchestrator
Accès SSH distant	Connexion SSH pour chaque action	Message Telegram depuis le mobile
Commandes complexes	Mémoriser les commandes Docker	Langage naturel + menus
Sécurité	SSH exposé	Bot authentifié + whitelist
Réactivité	Pas de notification des problèmes	Alertes + actions immédiates

Pourquoi un refactoring en sub-workflows (#273-#294) ?

L’orchestrateur initial avait grossi à 224 nodes au point de rendre l’UI N8N lente et l’édition risquée (déplacer un node pouvait casser des connexions hors écran). Trois vagues de refactoring ont ramené le parent à 124 nodes en extrayant les chemins fire-and-forget :

Vague	Issue	Effet
Phase 1	#273	224 → 142 nodes (5 SWs)
Phase 2	#273	142 → 98 nodes (5 SWs supplémentaires)
Conv Mgr	#278	47→21 + 32 (Conversation Command Handlers)
SH-N8N	#279	Service Handler N8N 40→6 + SH-N8N Action Executor 37
Photo routing	#176	+9 nodes pour photo conv-routing + SW-13
MCP menu	#294	Conv Agent 16→21 + SW-11 72→87

Le contrat de chaque SW est strict : entrée passthrough ou typée, sortie ignorée par le parent (pour les fire-and-forget), pas d’effet de bord sur le runtime principal.

Fonctionnalités clés

Fonction	Description
Authentification	Whitelist d’utilisateurs, approbation admin, ban list
Intent detection	Claude analyse le langage naturel (5 services)
Menus interactifs	Boutons inline pour actions fréquentes
Multi-service	Docker, N8N, Odoo, Content depuis une interface unique
Voice + Photo	Transcription audio + extraction d’images
Conversations	Multi-tours avec mémoire Redis et tool calls
Plans d’action	Multi-étapes avec escalade hybride
MCP	Outils n8n natifs activables par conversation

3. Comment ? — Mise en œuvre technique

Authentification

Étape	Action
1. Extract user ID	Récupère `userId`, `chatId`, `firstName` du message ou callback
2. Check banned	Lookup Data Table `Telegram Banned Users`
3. Check authorized	Lookup Data Table `Telegram Authorized users`
4. Pending approval	Si non autorisé : Data Table `Telegram Pending Approvals` + alerte admin

IA Router (Claude)

Quand un message texte n’est pas une commande exacte et qu’aucune conversation n’est active, l’IA Router détecte l’intent via Claude (cli-ollama) :

const prompt = `Tu es un système de détection d'intent pour un assistant Telegram.
Retourne UNIQUEMENT un JSON valide (pas de markdown, pas de backticks).

Format: {
  "intent": "<action>",
  "service": "<odoo|n8n|docker|general>",
  "action": "<specific>",
  "params": {},
  "confidence": <0.0-1.0>
}

Services:
- odoo: factures, devis, contacts, clients, projets, CRM
- n8n: workflows, automatisations, executions
- docker: containers (restart, status, logs)
- general: conversation, questions générales

Message utilisateur: ${text}`;

Confidence	Comportement
≥ 0.7	Route directement vers le service
0.5 - 0.7	Demande confirmation (boutons)
< 0.5	Route vers `general`

Fallback chain : claude-sonnet-yolo (prioritaire) → claude-haiku-yolo (si quota) → keyword routing (si API down).

Service Handlers

Quatre service handlers spécialisés, chacun avec une responsabilité étroite :

Service Handler Docker

Action	Commande	Protection
`status`	`docker compose ps --format json`	Tous
`logs`	`docker compose logs --tail 100`	Tous
`restart`	`docker compose restart`	Sauf security-stack
`update`	`docker compose pull && up -d`	Sauf security-stack

Service Handler N8N (refactoring #279)

Le SH-N8N parent ne fait plus que la vérification admin + délégation. Toute la logique d’exécution N8N est dans SH-N8N Action Executor (37 nodes).

Action	Description
`list_workflows`	Liste workflows avec pagination
`toggle_workflow`	Active / désactive un workflow
`list_executions`	Dernières exécutions (filtres)
`execute_trigger`	Déclencher un workflow whitelisté

Trigger whitelist : seuls les workflows présents dans n8n_trigger_whitelist peuvent être déclenchés manuellement (rate limit : 1/min/workflow).

Service Handler Odoo (refactoring #187)

33 nodes après extension /projet. Couvre contacts, factures, devis, CRM, projets. Le sub-workflow Odoo Project Picker (SW-12) gère la pagination des projets quand la liste dépasse l’inline keyboard.

Service Handler General

10 nodes pour /help et le chat Claude générique (questions ouvertes hors service spécifique).

Binary Content Handler

Le Binary Content Handler (21 nodes) traite les médias :

Type	Pipeline
Photo	Vision OCR (sub-workflow 14n, classification + extraction structurée)
Voice	Voice Transcription (Groq ≤30s, ElevenLabs >30s)
vCard	Ingress Contacts → Odoo `res.partner`
PDF / vidéo	Extraction métadonnées + résumé

Vision OCR retourne un contrat {status, docType, extracted, text}. Selon le docType :

docType	Routing
`business_card`	Création contact Odoo via Ingress Contacts (fire-and-forget)
`invoice` / `screenshot` / `handwritten` / `general_document`	Affichage + bouton `[Discuter]` qui lance une conversation
`not_document`	Bascule vers IA Router pour traitement conversationnel
`error`	Notification d’erreur via Notification Hub

Convention de callbacks

# Navigation
menu_<section>                  → Menu (main, docker, n8n, odoo, help, notif, todo)

# Docker
menu_docker_stacks_<action>     → Liste stacks pour action
docker_<action>_<stack>         → Exécute action sur stack

# N8N (admin)
menu_n8n_workflows              → Liste workflows
n8n_wf_<id>                     → Toggle workflow
n8n_run_<id>                    → Exécuter workflow

# Conversations
conv_switch_<id>                → Changer de conversation active
conv_delete_<id>                → Archiver
plan_exec_<shortId>             → Exécuter un plan
plan_modify_<shortId>           → Modifier un plan
plan_cancel_<shortId>           → Annuler un plan

# User management
approve_<userId>                → Approuver utilisateur (admin)
deny_<userId>                   → Refuser utilisateur (admin)

# Photos (#176)
photo_discuss_<shortId>         → Lance une conversation autour de la photo
photo_dismiss_<shortId>         → Ignore la photo

# Notifications hub
notif_<action>_<id>             → approve / retry / details / ignore

Best Practice : `__rl` resource locator

Les nodes Execute Workflow MUST utiliser le format __rl pour workflowId, sinon ils échouent silencieusement au runtime :

{
  "workflowId": {
    "__rl": true,
    "value": "<workflow-id>",
    "mode": "id"
  },
  "options": {}
}

Le format plat {"mode": "id", "workflowId": "<id>"} produit “No information about the workflow to execute found” sans surface l’erreur.

4. Et si ? — Perspectives et limites

Limites actuelles

Limite	Impact	Mitigation
Latence Claude	2-5s pour intent detection	Cache des intents fréquents à concevoir
Pas de multi-langue	Prompts en français uniquement	Suffisant pour usage personnel
Rate limiting Telegram	30 messages/seconde max	Non atteint en usage normal
Photos non-document = 2 appels LLM	Detection + analyse générique	Acceptable pour le contexte conversation

Scénarios d’évolution

Si l’équipe passe en multi-utilisateurs :

Permissions granulaires par handler (actuellement : admin / non-admin)
Logs d’audit des actions par utilisateur
Notifications de groupe pour les actions critiques

Si besoin d’extension fonctionnelle :

Ajouter un service au Switch du Service Router (nouveau case)
Ou activer un serveur MCP via la commande /mcp dans une conversation
Le système est extensible par design — chaque ajout est isolé dans son sub-workflow

Si la latence devient critique :

Pre-fetch des Data Tables fréquentes en cache N8N memory
Pipelining des appels Odoo (déjà partiellement fait)
Migration des fire-and-forget vers une queue Bull dédiée

Pages liées

Infrastructure

N8N en mode Queue — Backend automation
AI Stack — cli-ollama pour intent detection

Workflows

Système conversationnel — Conversations multi-tours, plans, MCP
Content Pipeline — Capture de notes et articles
Voice Transcription — Transcription vocale
Docker Updates — Approbations DIUN via callbacks
Notification Hub — Routage notifications + callbacks
Error Handler — Capture des erreurs orchestrateur

Référence

Glossaire — Webhook, Callback, Intent, Sub-workflow