Le Hub (/hub/*)

Le Hub — tableau de bord de pilotage agentique

Le Hub est l'interface d'administration privée de Synedre OS. Accessible uniquement depuis le VPS du vaisseau-mère via un tunnel sécurisé, il permet de piloter l'ensemble du harnais agentique : agents, chantiers, runs, négociations, mémoire et infrastructure.

Une application cockpit dédiée

Le Hub repose sur une application Nuxt autonome, distincte de toute autre surface applicative. Elle n'hérite d'aucun module de localisation ni de gestion de thème : elle est en français uniquement et impose un affichage en mode sombre permanent (le commutateur clair/sombre a été retiré en mai 2026). Ce choix de sobriété visuelle reflète la nature opérationnelle de l'outil.

Architecture en couches fonctionnelles

Le Hub n'est pas un monolithe. Ses fonctionnalités sont réparties en modules indépendants, chargés comme des couches Nuxt (layers) au démarrage. Chaque couche apporte ses propres pages, ses propres API et son propre code serveur, découverts automatiquement par le moteur de routage.

On distingue deux catégories :

• Les composants noyau — pages et endpoints directement portés par l'application principale : tableau de bord général, vue des coûts, gestion des sauvegardes, cadran de maintenance.
• Les modules thématiques — chacun encapsule un domaine métier ou technique et expose ses propres routes /hub/* ainsi que ses propres endpoints d'API.

Au total, le Hub agrège 27 couches fonctionnelles actives, couvrant des domaines aussi variés que la gestion des agents, le suivi des chantiers, la facturation, la mémoire, les automates, le monitoring SEO ou encore la formation interne.

Note architecture : ces couches sont déclarées via la clé extends: de la configuration Nuxt, et non via la clé modules:. Une confusion entre les deux entraîne des erreurs de chargement au démarrage. Chaque couche possède son propre fichier de configuration Nuxt minimal.

Carte des pages et modules

Pages noyau

L'application principale expose directement plusieurs pages de pilotage global :

• Racine /hub — redirection automatique (302) vers le tableau de bord principal ; ce n'est pas une page autonome.
• Vue SRE — supervision de la fiabilité du vaisseau-mère.
• Vue des coûts — suivi des dépenses, accessible depuis la navigation principale ; une sous-vue détaillée ventile les coûts par chantier et par budget annuel.
• Vue apprentissage agentique — tableau de suivi de la montée en compétence.
• Vue des sauvegardes — état des sauvegardes de l'infrastructure.
• Cadran de maintenance — interface de supervision de la santé documentaire et technique du système, détaillée ci-dessous.

Cadran de maintenance — deux onglets

Le cadran de maintenance est l'observatoire interne de la santé du système. Il se compose de deux onglets :

1. Tableau de bord de santé — une jauge globale agrège quatre dimensions de santé du système : proprioception, dette technique, apprentissage et automates. Un graphique d'évolution sur 7 jours accompagne un tableau de dérive documentaire, classant les écarts selon leur nature : référence morte, document publié obsolète, code plus récent que la doc, document non publié.
2. Regard extérieur — l'opérateur sélectionne un chapitre de documentation publique, génère un prompt épuré de toute donnée sensible, le soumet à un modèle IA externe, puis colle la réponse dans le formulaire pour archivage. L'historique des soumissions est consultable. La taille maximale d'une réponse soumise est de 50 000 caractères. Onze chapitres sont éligibles à cette revue externe.

Pages portées par les modules thématiques

Les 27 modules contribuent collectivement 49 pages supplémentaires sous /hub/*. Le tableau ci-dessous en donne la répartition par domaine fonctionnel :

Domaine fonctionnel	Pages /hub/*
Agents & opérations agentiques	38 pages : tableau de bord principal, fiches agents, brainstorm, chantiers (liste, fiche, kanban, travail), clients, conseil, constitution, dispatch, doctrine, emails, hooks, inbox, juridique, mémoire (navigation, recherche RAG), négociations, questions, reactor, runs (liste, fiche, atlas), sessions, paramètres, compétences, compétences en attente, modèle utilisateur
Backlog & planning	3 pages : backlog, planning, backlog système
Cockpits & chantiers	2 pages : fiche chantier, vue cockpits
Exercices & entraînement	2 pages : liste des exercices, détail par agent
Cicatrices	1 page : registre des cicatrices
Conduites	1 page : tableau des conduites
Automates	1 page : gestion des automates système
Monitoring SEO	1 page : cockpit SEO technique multi-tenant (taux 404, tendance clics/impressions, mode observation ou auto-remédiation, journal des alertes) — accessible par URL directe, absent de la navigation latérale

Surface publique du module Exercices : ce module expose également quatre pages publiques sur synedre.com (hors espace /hub) : liste des exercices, historique, cicatrices et détail d'une épreuve. Ces pages ne sont pas comptées dans les 49 pages hub ci-dessus.

Modules sans page Vue (server-only)

Plusieurs modules n'exposent aucune page d'interface. Ils fournissent exclusivement des endpoints d'API et une couche de persistance, consommés par d'autres pages du Hub ou par les automates Python. Ils couvrent notamment : la gestion académique interne, le suivi des articles autoblog, la configuration client, la messagerie quotidienne, la facturation, les incidents, les réunions, les outils utilitaires et d'autres services transverses.

Un module dédié aux statistiques du Hub expose les données de synthèse (/api/stats), les ressources de constitution et de charte (/api/un composant interne, /api/un composant interne) ainsi que les statistiques d'avatar — sans jamais présenter de page d'interface propre.

À noter : le module de pages d'expertise contribue des pages SEO publiques (hors /hub/), pas des pages de cockpit.

Navigation latérale — les sept zones

La barre de navigation du cockpit est organisée en sept zones thématiques, restructurées en mai 2026 pour refléter le flux de travail opérationnel :

Zone	Entrées
Pilotage	Tableau de bord principal · Emails · Brainstorm · Modèle utilisateur
Business	Clients · Négociations · Conseil · Juridique
Exécution	Backlog · Chantier · Runs · Questions · Nouvelle tâche · Sessions
Doctrine & Apprentissage	Doctrine · Constitution · Cicatrices · Exercices
Agentique	Agents · Reactor · Compétences · Compétences en attente · Automates système · Dispatch · Hooks & Réflexes · Apprentissage agentique
Mémoire	Brain (navigation mémoire) · Recall RAG (recherche sémantique)
Système	SRE · Cadran de maintenance · Coûts · Sauvegardes · Paramètres

Un lien séparé, placé en bas de la navigation, donne accès à la surface e-commerce PaaS. Cette surface est servie par une application distincte du cockpit Synedre OS — il ne s'agit pas d'une page interne au Hub.

Comportement actif : une entrée de navigation est marquée comme active sur correspondance exacte de la route courante ou sur correspondance de préfixe (sous-route). La racine /hub redirige systématiquement vers le tableau de bord principal et ne constitue pas une destination propre.

Les trois familles d'endpoints

Le découpage des routes API n'est pas qu'organisationnel : il porte une sémantique de droits. Trois préfixes coexistent, chacun avec son niveau de protection.

• /api/bo/* — surface back-office « fondateur/cron », protégée en amont par la porte d'infrastructure, parfois sans garde applicative supplémentaire.
• /api/hub/* — surface cockpit employé, avec vérification de session quasi-systématique.
• /api/voice/* — transcription audio, avec vérification de session et défense CSRF.

Surface back-office

Cette famille regroupe les endpoints réservés aux opérations fondateur et aux tâches planifiées. Elle se répartit en plusieurs sous-domaines fonctionnels :

• Apprentissage : consultation du fil d'apprentissage, application et mise à jour d'entrées.
• Chantier : déclenchement et édition d'explosions de chantier, consultation du statut, lancement de phase.
• Indicateurs de qualité : lecture des KPI de cicatrices.
• Coûts : tableau de bord, budget (lecture/écriture), séries temporelles, vision par chantier.
• Boîte de réception : synchronisation, liste, détail, pièces jointes, liaison à un chantier.
• Infrastructure vaisseau-mère : liste des sauvegardes, téléchargement, lecture de l'état de santé de la documentation et de la dérive détectée.
• Revue externe de la documentation : liste des chapitres éligibles, génération du prompt nettoyé pour un modèle IA externe, historique des revues (avec filtres), soumission d'une revue externe.
• Métriques SRE : lecture des métriques de fiabilité.
• Tenants : statut d'expédition automatique par tenant.

Particularité d'authentification : certains endpoints de cette surface s'appuient exclusivement sur la porte d'infrastructure (cookie de knock + slug) plutôt que sur la vérification de session applicative. C'est notamment le cas de l'endpoint de synchronisation de la boîte de réception, déclenché par une tâche cron système.

Ce choix est lié à une contrainte technique : la synchronisation IMAP bloque la boucle d'événements Node.js et reste donc exclue du planificateur interne. Les sept autres tâches périodiques sont, elles, gérées par ce planificateur :

• Traitement de la file d'e-mails (toutes les 2 minutes)
• Surveillance de disponibilité (toutes les 15 minutes)
• Veille du dictionnaire (toutes les 30 minutes)
• Surveillance des dépendances (quotidien, 2 h)
• Réunion quotidienne d'audit (quotidien, 8 h)
• Surveillance des certificats SSL (quotidien, 9 h)
• Veille de marque (quotidien, 12 h)

Surface cockpit employé

Cette famille est de loin la plus volumineuse. Elle regroupe les endpoints utilisés par les interfaces du cockpit : gestion des agents, des chantiers, des runs, des négociations, du conseil, des clients, du brainstorming, de la mémoire, de la doctrine, des compétences, des sessions, des questions, des tâches, du modèle utilisateur, des paramètres, de la répartition des agents et de l'atlas.

La vérification de session employé est appliquée dans la grande majorité des fichiers de cette surface. Les exceptions sont des helpers internes ou des flux SSE (Server-Sent Events). Le pattern standard s'écrit :

export default defineEventHandler(async (event) => {
  requireEmployeeSession(event)
  // …
})

Un sous-ensemble d'endpoints gère spécifiquement la vie d'un chantier : runs actifs, bugs découverts, sessions CLI (démarrage, arrêt, réinitialisation), flux d'événements agent en temps réel (SSE), ainsi que les actions sur un run donné (brouillon de réponse, déclenchement de correctif, profil, flux d'événements).

Surface de transcription audio

Un unique endpoint accepte un fichier audio WAV en multipart et retourne le texte transcrit, la locale détectée, la durée en millisecondes, le modèle utilisé et le backend sollicité. La locale par défaut est le français.

Les garde-fous appliqués sont les suivants :

• Vérification de session employé obligatoire.
• Taille maximale de fichier : 5 Mo.
• Limite de débit : 100 transcriptions par tranche de 5 minutes par session.
• L'audio n'est jamais persisté sur disque : traitement en mémoire vive uniquement.
• Défense CSRF par vérification de la correspondance Origin/Referer avec le Host.

Authentification

Le modèle en deux couches

La sécurité repose sur une architecture à deux niveaux indépendants :

• Couche infrastructure : tunnel chiffré vers le port local du serveur, combiné à une porte de knock nginx (cookie + slug). Toute requête qui franchit cette porte est déjà qualifiée « propriétaire ».
• Couche applicative : un middleware de démarrage injecte automatiquement un cookie de session signé « fondateur » pour toute requête qui n'en présente pas. En conséquence, la vérification de session applicative passe toujours sur le runtime vaisseau-mère — la sécurité réelle est entièrement portée par l'infrastructure.

Ce middleware d'auto-session est strictement limité au vaisseau-mère. Il n'existe pas dans le cœur du produit ni dans les instances tenant. Sur les tenants publics, la vérification de session reste obligatoire et constitue la vraie garde applicative.

Les fonctions de vérification de session

Quatre fonctions utilitaires encadrent le contrôle d'accès applicatif :

• Lecture de session : décode le cookie de session (JSON signé HMAC-SHA256). Retourne null si le cookie est absent ou invalide.
• Garde employé (requireEmployeeSession) : renvoie la session si le type d'utilisateur est employee, déclenche une erreur 401 sinon. C'est la garde standard des surfaces cockpit et transcription.
• Garde fondateur : exige en plus le statut Super-Admin SaaS, erreur 403 sinon.
• Garde par rôle : exige un rôle métier donné ou le statut Super-Admin SaaS.

La liste des Super-Admins SaaS est une liste blanche statique dans le code source — volontairement non stockée en base de données, de sorte que toute modification exige un changement de code et une revue explicite.

La session porte les champs suivants : identifiant employé, e-mail, prénom, nom, rôle, identifiant de profil, identifiant client, type d'utilisateur, indicateur administrateur.

Le middleware de routage est désactivé

Le middleware de routage Nuxt côté cockpit est intentionnellement réduit à un no-op (il retourne immédiatement sans effectuer aucun contrôle). La porte nginx et le tunnel chiffré assurent la protection en amont ; un contrôle supplémentaire côté Nuxt serait redondant.

Ce middleware reste déclaré car de nombreuses pages y font référence dans leurs métadonnées de route. Le no-op étant volontaire, cette déclaration n'a aucun impact fonctionnel.

Layout du cockpit

Le cockpit repose sur un layout unique qui structure l'ensemble des pages de l'interface. Ce layout n'hérite d'aucun layout parent : le vaisseau-mère est une application autonome.

Points notables :

• L'identité affichée dans l'interface est un stub statique — l'authentification dynamique Nuxt a été retirée ; c'est la couche infrastructure qui garantit l'identité réelle de l'opérateur.
• Le titre des pages suit le gabarit … — Synedre OS.
• Les pages temps-réel (reactor, cockpit chantier) sont rendues côté client uniquement (ssr: false), ce qui leur permet de maintenir des connexions SSE persistantes.

Note de cohérence : le commentaire d'en-tête du layout liste les entrées de navigation de façon incomplète. La structure de navigation réelle, définie dans le tableau des sections du layout, fait toujours foi sur ces commentaires.

Les surfaces console du Hub

Le Hub expose plusieurs consoles de pilotage des agents. Chaque console est une vue spécialisée sur un type d'activité : exécutions en cours, chantiers de développement, négociations commerciales, supervision de flotte, ou vue orbitale temps réel. Les données sont centralisées dans un modèle partagé, exposé via des entités métier Python et des tables relationnelles.

Exécutions scopées (Runs)

Un run représente une exécution scopée d'Atlas — qu'elle soit déclenchée par email, par chat console, ou par un cron. Chaque run porte les attributs suivants : identifiant unique, source de déclenchement, type de trigger, périmètre (vaisseau-mère ou tenant), titre, statut, type et identifiant de référence, dates d'ajout et de fin.

• Source atlas-inbox : run déclenché par un email entrant.
• Source console : run déclenché par le chat du Hub.
• Les emails classifiés comme question, bruit ou intention de chantier ne génèrent pas de run : ils restent dans leurs espaces dédiés (questions, chantiers).
• Un run d'exécution d'automate (task run) est une entité distincte — ne pas confondre avec un run Atlas.

La vue runs liste toutes les exécutions, filtrables par périmètre. Une vue détaillée par agent permet de consulter le fil d'événements en temps réel via un flux SSE, de lire ou poster un brouillon de réponse, et de déclencher un correctif.

Chantiers, travaux et tâches

Un chantier est l'unité de pilotage d'un projet de développement. Il se décompose en travaux, eux-mêmes décomposés en tâches. Cette hiérarchie à trois niveaux structure l'ensemble du suivi opérationnel.

Modèle hiérarchique

• Chantier : projet, porté par une entité dédiée. Lié à N travaux.
• Travail : unité de livraison au sein d'un chantier. Lié à N tâches.
• Tâche : action atomique. Peut dépendre d'autres tâches (graphe orienté acyclique).
• Des tables de liaison associent agents et chantiers d'une part, agents et travaux d'autre part.

La création canonique d'un chantier passe par une procédure en sept étapes qui initialise le squelette complet (chantier + premiers travaux + tâches).

Note d'architecture : le modèle de données présente une dette de nommage historique. Les entités chantier et travail utilisent un préfixe hérité de l'ère PaaS, tandis que les tâches et les tables de liaison ont déjà migré vers le préfixe cible. Il n'existe pas de vue ou table intermédiaire portant le nouveau préfixe pour les chantiers et travaux eux-mêmes — la migration est en cours selon le pattern Strangler Fig.

Entités de contrôle de concurrence et d'audit

Composant	Rôle	Points clés
Verrou de chantier	Empêche deux sessions de modifier simultanément le même chantier	Clé composite (chantier × type de propriétaire) ; propriétaires possibles : session utilisateur ou sous-processus agent spawné. TTL 30 min avec heartbeat. Mode de compatibilité descendante si la table est absente.
Erreur de verrouillage	Exception levée quand le verrou est tenu par une autre session active	Interceptée par la couche compétence chantier avant toute modification.
Journal d'audit des explosions	Trace chaque invocation du pipeline de découverte automatique de travaux	Une ligne par invocation ; cycle de vie pending → success | validation_failed | llm_failed | killswitched. Stocke le modèle IA utilisé, le fournisseur, les tokens consommés, le coût estimé, le plan JSON produit et le nombre de travaux créés. Rétention 90 jours. Un quota sur 24 h déclenche un kill-switch configurable.
Dépendances de tâches (DAG)	Modélise les relations de blocage entre tâches au sein d'un travail	Validations à l'ajout : pas d'auto-dépendance, tâches dans le même travail, pas de cycle (détection DFS). Lève des exceptions typées pour cycle détecté ou tentative de dépendance inter-travaux.

Vues et fonctionnalités de la console chantiers

• Vue liste des chantiers actifs et vue kanban par travail.
• Vue cockpit : sessions agents en cours sur un chantier.
• Console CLI en direct : démarrage, arrêt, reset de session, flux d'événements agents en temps réel (SSE).
• Actions disponibles : rédiger la mission, lancer en mode automatique, archiver, clore avec brouillon d'email, basculer en brainstorming, gérer les livrables, gérer l'équipe, auditer la pertinence.

Console CLI Synedre

Le cockpit embarque une surface de pilotage d'une session Claude CLI réelle, accessible depuis le navigateur. Le mécanisme repose sur un daemon côté machine hôte (et non dans un container isolé) qui relaie les interactions.

• Statut : interroge le daemon et retourne un état { ok, alive, info }. Si le daemon ne répond pas, la surface renvoie alive: false sans exposer le message d'erreur interne au client — comportement de sécurité explicite.
• Envoi de touches : transmet des entrées clavier à la session active.
• Flux temps réel : stream SSE de la sortie de la session.

Point d'attention : l'architecture daemon hôte (et non container) est intentionnelle — elle résout un problème d'isolation identifié lors d'un travail dédié à ce sujet.

Négociations

Les négociations modélisent le pipeline de traitement des leads entrants. Un email reçu est analysé par Atlas ; si l'intention détectée est negociation, un item de négociation est créé et apparaît dans la console dédiée.

• Vue liste des négociations en cours et vue détail par négociation.
• Actions disponibles sur une négociation : assigner, gérer les contacts, gérer les livrables (dont les fichiers joints), consulter les emails liés, créer un événement, suivre la timeline, gérer les propositions commerciales.
• Sur chaque proposition : endpoint de décision (accepter / refuser).
• Action de démarrage de travail : bascule la négociation vers un chantier opérationnel.

Module flotte (Fleet)

Le module flotte est un composant serveur uniquement, sans interface Hub propre à ce jour. Il expose un schéma de données destiné à être consommé par une future interface dédiée.

Le modèle de données du registre de flotte inclut, pour chaque instance client : identifiant, nom, domaine, offre souscrite, MRR, frais de setup, statut, région du VPS, URL d'administration, fournisseur IA et modèle IA configurés.

Avertissement : ce registre comporte des colonnes historiques destinées à stocker des secrets (mots de passe d'administration, clés API). Ce schéma est hérité de l'ère PaaS et est incohérent avec la doctrine zéro-secret en base de données métier. Il est en attente d'audit et ne doit pas être considéré comme la source canonique des secrets opérationnels.

La source de vérité opérationnelle pour le pilotage des VPS clients reste le registre VPS principal. La relation exacte entre ce registre et le modèle flotte est à confirmer. Le pilotage opérationnel des tenants s'effectue principalement via les consoles d'administration des sites et des clients.

Vue orbitale — Réacteur

La vue Réacteur est une représentation orbitale en direct de l'activité des agents. Elle s'organise en trois anneaux concentriques selon le rôle de chaque agent :

• Anneau 1 (centre) : agents de direction.
• Anneau 2 : agents de cadrage et d'exécution.
• Anneau 3 (périphérie) : agents de validation.

Un logo pieuvre occupe le centre. La vue est alimentée en temps réel par SSE. Elle est rendue côté client uniquement (pas de rendu serveur). Elle est adaptée de la page marketing publique du réacteur.

Points d'entrée pour étendre le Hub

Objectif	Mécanisme
Ajouter une entrée dans la barre latérale	Modifier le tableau de sections de navigation dans le layout Hub principal.
Ajouter une page /hub/X	Créer la page dans le module concerné et déclarer le layout hub dans les métadonnées de page.
Ajouter un endpoint cockpit	Créer l'endpoint dans le dossier API du module concerné et y appliquer le middleware de vérification de session employé.
Comprendre l'authentification	Consulter les utilitaires de session et le middleware d'auto-session, qui gèrent la signature HMAC des cookies de session Hub.
Brancher un nouveau module	Déclarer le module dans la configuration d'extension Nuxt et fournir un manifeste et une configuration locale au module.
Travailler sur les exécutions et chantiers (base de données)	Passer par les entités métier Python du dépôt et les tables correspondantes : runs Atlas, chantiers, travaux, tâches, négociations — toutes dans le schéma du vaisseau-mère.
Consulter le cadran de maintenance et de dérive documentaire	Utiliser la vue de maintenance du Hub et son endpoint associé, qui exploitent les tables de santé documentaire et de dérive détectée.
Revue externe de documentation	Utiliser le composant de panneau de revue externe et ses endpoints dédiés, appuyés sur la table de revues externes.
Registre des réflexes et hooks	Consulter la vue hooks du Hub et son endpoint de listing, qui expose le registre des réflexes organisés par niveau (tronc / bras).
Verrou de chantier (concurrence CLI)	Utiliser l'entité de verrouillage distribuée : opérations try_acquire, force_claim, release, heartbeat.
Audit des invocations de découverte automatique	Consulter l'entité d'audit : méthodes de recherche des invocations récentes et de comptage sur 24 h.
Dépendances de tâches (DAG)	Utiliser l'entité de dépendances : opérations add_dep, remove_dep, list_deps_for_travail avec détection anti-cycle DFS.

Gestion des secrets : aucun secret n'est stocké en clair dans le code. La clé de signature des cookies de session Hub est consommée via HMAC par la couche cryptographique de session ; sa variable d'environnement réside dans les fichiers d'environnement exclus du dépôt, conformément à la doctrine des secrets.