Aller au contenu

Architecture

Cette page explique les choix structurants de Kirexo — pas comment faire, mais pourquoi. Pour l'inventaire complet des règles et des patterns attendus, voir CLAUDE.md à la racine. Pour le cadrage fonctionnel et la liste des services backing, voir projet.md.

Pourquoi dunglas/symfony-docker et FrankenPHP

Le bootstrap du projet se base sur dunglas/symfony-docker, qui s'appuie sur FrankenPHP. Cette brique nous donne HTTP/2, HTTP/3 et surtout le worker mode PHP natif — un interpréteur qui reste chargé entre les requêtes, sans FPM ni overhead de bootstrap Symfony à chaque appel. En dev, on y gagne une boucle de feedback rapide ; en prod, on y gagne une latence très basse sans jongler avec php-fpm, une reverse-proxy supplémentaire et un Caddy/Nginx séparé. Les prérequis locaux restent minimaux : git, docker, docker-compose, castor, jq, glab. Rien d'autre, volontairement — aucun PHP ou Node installé côté hôte, tout vit dans les conteneurs.

Le worker mode est activé de bout en bout : Symfony le supporte nativement via public/index.php depuis la 7.4, sans qu'il faille installer un package runtime/* ni surcharger APP_RUNTIME. La seule configuration vit dans le Caddyfile de FrankenPHP, qui pointe le worker sur l'entrée HTTP standard du projet. Conséquence pratique : pas de double chemin de boot (FPM d'un côté, worker de l'autre) à maintenir, et pas de dépendance tierce dont le support Symfony serait à surveiller.

Pourquoi des services synchrones par défaut (et Messenger réservé à l'asynchrone réel)

La logique applicative interne de Kirexo — rendu des pages, dashboards, actions simples — passe par des services applicatifs synchrones injectés directement : controller → service → repository. Les controllers restent fins : ils délèguent à un service, ils ne calculent pas eux-mêmes. C'est le mode par défaut, et il couvre la quasi-totalité des écrans de la plateforme.

Le bus Messenger n'est pas le chemin par défaut. Il est réservé à deux cas précis :

  • l'asynchrone réel — les écritures qu'on veut découpler de la requête utilisateur, acheminées via RabbitMQ (typiquement la diffusion d'un article publié vers les plugins) ;
  • une opération sur route dédiée de style API Platform (State Provider/Processor), où le pattern impose le passage par un message.

Le query.bus n'est pas imposé pour les lectures ni pour la logique interne : un dashboard qui compte les articles publiés appelle directement le repository via son interface, sans message de lecture intermédiaire.

Ce choix évite la cérémonie d'un message + Handler pour des cas qui n'en tirent aucun bénéfice (une lecture synchrone n'a pas besoin d'être découplée), tout en gardant le découplage asynchrone là où il compte vraiment : une publication qui déclenche N diffusions plugin ne doit jamais bloquer la requête, et l'isolement par transport permet de faire tomber un plugin sans faire tomber les autres ni le cœur. La règle complète est le pattern 1 de CLAUDE.md.

Pourquoi les plugins sont des Symfony Bundles isolés

Chaque destination de diffusion (Mastodon, RSS, web, API, et plus tard Telegram, LinkedIn, Discord…) est un Symfony Bundle autonome, implémentant une interface commune (DiffusionPluginInterface), auto-enregistré par tag de service, et relié au cœur uniquement par des événements.

La communication par événements se décline en deux modes, synchrone par défaut :

  • événements Symfony (EventDispatcher, synchrones, in-process) quand un plugin doit réagir ou contribuer dans le cycle de la requête ;
  • événements Messenger/RabbitMQ (un transport par plugin) pour la diffusion découplée — typiquement ArticlePublished. Chaque plugin consomme via son propre transport : un échec côté Mastodon ne fait pas tomber la diffusion RSS.

On ne bascule sur le mode asynchrone que quand le découplage le justifie réellement (une diffusion réseau lente qu'on ne veut pas voir bloquer la requête) ; sinon l'événement synchrone in-process suffit et reste plus simple à raisonner et à tester.

La contrainte forte est qu'un plugin doit pouvoir être supprimé sans toucher au reste. C'est cette contrainte qui force le couplage à passer exclusivement par l'interface et par les événements — pas par des appels directs, pas par une entité Doctrine partagée, pas par un service injecté depuis le cœur. Le prix à payer est une surface d'interface un peu plus large ; le bénéfice est qu'ajouter une nouvelle destination ne demande jamais de modifier le cœur. La règle complète est le pattern 2 de CLAUDE.md.

Pourquoi le fuseau PHP est figé en dev et choisi à l'installation en production

Le fuseau horaire se règle par la variable standard TZ, mais elle n'a pas la même portée selon l'environnement. En production, elle pilote PHP lui-même : frankenphp/conf.d/10-app.ini déclare date.timezone = ${TZ:-UTC}, et compose.prod.yaml transmet TZ (défaut UTC) aux services php et worker. En dev et en CI, elle ne touche que le shell : l'image de dev ajoute frankenphp/conf.d/20-app.dev.ini, qui repose date.timezone = UTC après 10-app.ini.

En dev et en CI : un shell local, un PHP en UTC

Le conteneur de dev tourne avec TZ=Europe/Paris (compose.override.yaml). Cette valeur ne sert qu'à des consommateurs périphériques : le shell, la commande date, les logs Docker, la statusline de l'IDE. Elle évite le décalage gênant à la lecture de docker compose logs (« il est 20 h chez moi, pourquoi ça affiche 18 h ? »). C'est un confort de lecture, rien de plus.

PHP, lui, reste en UTC. La raison est la reproductibilité : la CI utilise la même image de dev, sans TZ. Si le fuseau de PHP suivait celui du poste, les dates calculées par les tests et les fixtures dépendraient de la machine, et un test vert en local pourrait rougir en CI, ou l'inverse. Épingler UTC dans 20-app.dev.ini, fichier absent de l'image de production, garantit les mêmes résultats partout sans rien imposer à la production.

En production : un choix de l'exploitant, fait une fois

Une installation tierce peut vouloir lire ses dates dans son fuseau. Le fuseau est donc réglable par TZ, avec UTC par défaut, et la même valeur sert au conteneur et à PHP.

Cette liberté a un prix, qui tient au stockage. Les colonnes de date sont en Types::DATETIME_IMMUTABLE, c'est-à-dire en timestamp without time zone côté PostgreSQL, et aucune requête ne s'appuie sur NOW() ou CURRENT_TIMESTAMP : c'est PHP qui fournit l'heure, dans son fuseau, et la base l'enregistre sans rien dire de ce fuseau. Deux conséquences en découlent :

  • changer TZ après coup décale tout l'historique. Les dates déjà écrites restent des heures locales de l'ancien fuseau, relues comme des heures du nouveau. Aucune migration ne les convertit, et rien ne signale le décalage. TZ se choisit donc à l'installation et ne bouge plus ;
  • l'heure d'hiver crée une ambiguïté annuelle. Pendant l'heure qui se répète au passage à l'heure d'hiver, deux instants distincts portent la même heure locale. Tris et comparaisons peuvent alors se décaler d'une heure, une fois par an. En UTC, ce cas n'existe pas.

D'où la recommandation de garder UTC sauf besoin réel. Le piège le plus probable n'est pas un choix délibéré mais un choix involontaire : ${TZ:-UTC} reprend tout TZ exporté par le shell qui lance docker compose, si bien qu'un changement de profil sur le serveur suffit à déplacer le fuseau au déploiement suivant.

L'alternative écartée

Une approche plus robuste existe : garder PHP en UTC partout et ne convertir vers le fuseau de l'utilisateur qu'au moment du rendu (fuseau par défaut du filtre Twig date, formatters côté front). Les dates stockées seraient alors indépendantes de toute configuration, et le fuseau pourrait changer sans rien décaler. Ce n'est pas la solution retenue. Le réglage par TZ agit au niveau de PHP, sans toucher au rendu, et reporte en échange sur l'exploitant la contrainte de ne jamais changer de fuseau.

La référence de la variable, cas limites compris (valeur vide ou invalide), est dans Fuseau horaire (TZ).

Pourquoi Diátaxis pour la documentation

La documentation suit Diátaxis, qui impose quatre quadrants strictement séparés : Tutoriels (apprendre en faisant), Guides (résoudre un problème précis), Référence (consulter la vérité) et Explications (comprendre le pourquoi — cette page). Chaque document appartient à un seul quadrant. Cette contrainte évite les pages-fourre-tout qui essaient d'expliquer et d'enseigner et de lister exhaustivement, et qui finissent par mal faire les trois.

La doc est publiée via mkdocs (thème material, image custom définie dans mkdocs/Dockerfile) et servie en local par le service Docker docs démarré avec la stack (castor docker:up). Elle n'est plus atteinte par un port publié sur la loopback mais par le proxy hôte, sous https://docs.main.localhost pour le dépôt principal et https://docs.<worktree>.localhost dans un worktree — depuis l'intérieur d'un conteneur, par l'alias applicatif http://docs-int:8000 (cf. Routage des worktrees : DNS, TLS et cloisonnement réseau). L'image custom ajoute deux plugins : git-revision-date-localized (date de dernière modif de chaque page, lue depuis git) et social (génération automatique des images Open Graph de partage). Toute modification qui change ce que l'utilisateur perçoit depuis un navigateur, ou qui introduit un concept utilisateur (nouveau plugin, nouvelle commande Castor exposée, nouvelle variable d'environnement), doit s'accompagner d'une doc à jour — c'est une règle non négociable de CLAUDE.md.