telaria-app — architecture de l'application assemblée

Ce que c'est

telaria-app est une application web Symfony 8 / PHP ≥ 8.4 conçue comme un assembleur mince. Elle ne porte pas l'essentiel de la logique métier : celle-ci vit dans quatre bundles maison qu'elle wire et surcharge. L'application apporte, en propre : la couche utilisateur/authentification, la surface web (contrôleurs, routes, templates), l'API, et quelques extensions applicatives (SEO, config chatbot, validation IA de la veille, anti-spam IA du contact).

Elle sert une vitrine web multi-sites, deux viewers de documentation, des assistants conversationnels RAG, un espace lecteur connecté, un formulaire de contact protégé et un back-office /admin de production doc-IA.

Frontières de composition

L'application se compose de quatre bundles maison plus son propre cœur applicatif. Chaque bundle est une dépendance Composer (VCS) enregistrée pour tous les environnements.

Principe : les bundles référencent l'utilisateur par interface ; l'application fournit l'implémentation concrète via la résolution d'entités cibles Doctrine (CmsUserInterface et VeilleReaderInterface → App\Entity\User). L'application étend les données des bundles sans modifier leurs tables, via des entités companion en relation OneToOne (SEO sur le contenu CMS, verdict de validation sur l'item de veille, réglages de prompt sur le chat).

Contrats de wiring (config des bundles)

• Vitrine multisite : une liste blanche vitrine_allowed_routes définit les routes servies sur un site non primaire ; tout le reste renvoie 404 (via un subscriber du bundle). Les noms de routes appartiennent à l'application, d'où un couplage explicite app ↔ bundle déclaré côté config.
• RAG : la racine indexée est le dossier docs/ (prévu comme sous-module Git). Politique observée default-allow (indexe tout sauf une liste d'exclusions) ; embeddings délégués à un microservice externe (URL via variable d'environnement) ; paramètres de chunking et de retrieval fixés en config ; store = base + extension vectorielle (chemins via variables d'environnement).
• MCP : version de protocole et quota par (tenant, outil) fixés en config ; le quota est branché sur un rate limiter Symfony dédié injecté dans la passerelle du bundle.
• Routes importées : les bundles MCP et CMS/socle exposent leurs routes via import. Les contrôleurs de l'application sont chargés en double : une variante localisée préfixée /{_locale} (préfixe de nom localized_) et une variante par défaut ; l'API est exclue du préfixe de locale.

Architecture de sécurité

Entité utilisateur

App\Entity\User est l'entité applicative centrale. Champs de contrat : email (identifiant unique de connexion), password (hashé), roles (ROLE_USER toujours garanti), isVerified, apiToken (nullable, stocké hashé SHA-512), et les champs 2FA (is2faEnabled opt-in, authCode, totpSecret, trustedVersion).

Elle implémente les contrats Symfony (UserInterface, PasswordAuthenticatedUserInterface, TwoFactorInterface, TrustedDeviceInterface) et les contrats des bundles (CmsUserInterface, VeilleReaderInterface).

Firewalls et contrôle d'accès

• api (^/api/) : stateless, provider par apiToken, authenticator custom déclenché par le header X-Auth-Token.
• main : reste du site, provider par email, form_login avec CSRF + 2FA + logout.
• Contrôle d'accès : ^/admin → ROLE_ADMIN ; ^/api → ROLE_USER. Hiérarchie : ROLE_ADMIN ⊃ ROLE_USER.
• Redirection post-login selon le rôle (admin → dashboard, lecteur → espace lecteur).

Mécanismes transverses

• Auth API : token présenté hashé en SHA-512 puis comparé au token stocké ; rate-limité par IP ; échec → 401 JSON.
• 2FA email (scheb/2fa) : provider email actif globalement mais opt-in par utilisateur ; code à 6 chiffres ; appareils de confiance via cookie dédié.
• Basic Auth global (« public dans le privé ») : un listener sur kernel.request protège tout le site derrière un Basic Auth HTTP quand un drapeau d'environnement est actif, sinon reste inerte — ce qui rend les pages publiques réellement privées en environnement de préproduction.
• Reset password / vérification email : via bundles SymfonyCasts dédiés.

Surface web et endpoints (contrats de route)

Chaque route non-API possède une variante localisée localized_<nom> préfixée /{_locale}.

Public

Lecteur (ROLE_USER)

Admin (ROLE_ADMIN, préfixe /admin)

Familles de noms de routes : admin.dashboard.*, admin.cms.* (pages, sites, images, media), admin.veille.*, admin.corpus.*, admin.rag.*, admin.mcp.*, admin.metrics*, admin.chatbot.config, admin.chat.params, admin.users.*, admin.profile.*.

API (firewall api, stateless, préfixe /api)

Contrat du webhook de ré-indexation : la signature sha256=hmac_sha256(body, secret) est vérifiée en temps constant. L'endpoint ne réagit qu'à un événement de création de tag avec ref non vide (sinon 200 Ignoré) ; si aucun checkout n'est déjà en cours, il lance checkout + ré-indexation en fond → 202. Signature invalide → 401 ; payload non-JSON → 400. L'exécution effective (git + reindex) est déléguée à un contrat fourni par le bundle produit doc-IA ; l'application ne fait que valider la signature et déléguer.

Fonctions IA applicatives

Deux fonctions IA sont propres à l'application (au-dessus des bundles). Les deux appellent un modèle Claude rapide de la famille Haiku via l'API Anthropic Messages, sur clé API fournie par variable d'environnement, avec parsing tolérant (jamais d'échec silencieux du pipeline).

Validation automatique de la veille

Après chaque cycle de veille (message traité par le worker Messenger), un subscriber écoute l'événement de message traité et valide les items nouvellement proposed, dans le même process worker. Garde-fous observés :

• Désactivé si le prompt de validation n'est pas configuré (clé de réglage éditée en back-office).
• Limite de 20 items par cycle (garde anti-runaway), triés par date de traitement, uniquement ceux sans validation déjà persistée.
• Le prompt système = le prompt configuré par l'utilisateur ; le message utilisateur porte titre, résumé tronqué, source et thème.
• Verdict attendu ACCEPT|raison, REJECT|raison ou UNCERTAIN|raison. Réponse malformée → UNCERTAIN.
• Application : ACCEPT → item accepté (visible en vitrine et espace lecteur) ; REJECT → rejeté ; UNCERTAIN → reste proposed pour revue humaine. La raison est persistée dans une entité companion. Les erreurs d'appel sont loggées mais ne font pas échouer le cycle.

Frontière : le pipeline de collecte/résumé/proposition et l'entité VeilleItem (statuts proposed/accepted/rejected) viennent du bundle ; l'application ajoute le subscriber, le service d'appel, l'entité de validation et la section de config du prompt.

Anti-spam du contact

Le formulaire de contact combine plusieurs couches : rate limit, honeypot, CAPTCHA (Altcha, challenge/HMAC via variables d'environnement) et une analyse IA (ContactSpamAnalyzer) qui implémente le contrat de détection de spam du bundle.

Contrats de configuration

Toute la configuration sensible passe par variables d'environnement ; les fichiers versionnés ne contiennent que des placeholders. Contrats observés (usages, pas de valeurs) : framework (APP_ENV, APP_SECRET), base (DATABASE_URL), transport Messenger, mail (DSN, expéditeur, DKIM), CAPTCHA (secret + complexité), clé API Anthropic, secret HMAC du webhook, microservice d'embeddings et chemins du store vectoriel, drapeau + identifiants du Basic Auth global, throttle de reset, réglages du viewer docs, paramètres du pipeline de veille.

Rate limiters (politiques observées) : formulaire de contact (token bucket, quelques requêtes par fenêtre de minutes), API (token bucket, par IP), 2FA (token bucket serré), outil MCP (sliding window, par (tenant, outil), actif dans tous les environnements).

Points de contrat pour un intégrateur

• Identité : implémenter/mapper l'utilisateur derrière les interfaces des bundles ; ne jamais dupliquer, résoudre via resolve_target_entities.
• Extension de données de bundle : passer par une entité companion OneToOne, jamais par modification des tables du bundle.
• API : header X-Auth-Token (token hashé SHA-512 côté stockage), firewall stateless, réponses JSON.
• Webhook : signature HMAC-SHA256 en en-tête, vérification en temps constant, traitement asynchrone borné par un flag anti-concurrence.
• Multisite : toute nouvelle route destinée à la vitrine doit être ajoutée à la liste blanche, sinon 404 sur site non primaire.
• IA : les fonctions IA sont pilotées par des prompts configurables en back-office et bornées par des garde-fous (désactivation si non configuré, plafond par cycle, dégradation en UNCERTAIN).

Fiche de référence descriptive, généralisée depuis une rétro-doc code-first. Certains éléments marqués « à confirmer par le Dev » dans la source (politique default-allow du RAG, découpage des migrations par bundle, ouverture de l'inscription publique, choix d'appels IA non centralisés) restent à valider.