Temporal : comprendre l’architecture d’un cluster, Frontend, History, Matching, Web UI et persistance

Dans ce chapitre de la série Temporal, on pose le modèle mental minimal de l’architecture serveur : Frontend, History, Matching, Worker interne, couche Visibility, stockage et Web UI. En s’appuyant sur la vidéo Temporal - 02. Architecture d'un cluster et sur le dépôt temporal-tutorials, voici une lecture claire de ce qui tourne dans un cluster Temporal, de ce qui scale, et de la place exacte du SDK Python et des workers.

TL;DR

Temporal ne fait pas tourner votre code métier dans le serveur.

Le chapitre 02-architecture-overview/slides.md montre au contraire une séparation nette :

• le serveur Temporal orchestre, persiste l’historique, gère les timers et distribue les tâches ;
• vos workers exécutent le code des workflows et des activities dans vos propres processus ;
• le point d’entrée public est le service Frontend sur le port 7233 ;
• la Web UI est l’outil de debug principal et, en environnement local, elle est exposée par temporal server start-dev sur 8233 ;
• pour la persistance, le dépôt distingue bien SQLite en dev, puis PostgreSQL, MySQL ou Cassandra pour des usages durables.

S’il faut retenir une seule phrase, c’est celle-ci : server = orchestrateur, worker = exécuteur.

La vidéo de référence

Vidéo principale : Temporal – 02. Architecture d’un cluster

Playlist : Temporal – Tutorials

Auteur : xavki

Embed :

La page YouTube confirme le titre de l’épisode, son rattachement à la playlist Temporal, et une durée d’environ 16 minutes. Côté dépôt, le README.md positionne ce chapitre comme l’étape qui couvre les services du serveur, la persistance et la Web UI.

Architecture Temporal : c’est quoi exactement ?

Temporal est présenté dans le dépôt comme une plateforme de durable execution pour les traitements longs, stateful et critiques. Le chapitre précédent, 01-introduction/slides.md, explique déjà quand l’outil est pertinent : paiements, commandes, agents IA, CI/CD, ou toute orchestration multi-étapes qui doit survivre aux crashs et aux retries.

Le chapitre 02-architecture-overview/slides.md fait ensuite le travail essentiel : montrer que Temporal n’est pas juste une queue, ni juste un orchestrateur visuel. C’est un cluster composé de plusieurs services internes avec des responsabilités très précises :

• Frontend pour l’API publique gRPC ;
• History pour le cœur durable des workflows ;
• Matching pour la distribution des tâches aux workers ;
• Worker pour les workflows système internes à Temporal ;
• Visibility pour la lecture, la recherche et les listes de workflows.

Autrement dit, Temporal se comprend mal si on le réduit à un serveur + des workers. Le bon modèle mental est plutôt une couche d’orchestration durable + une couche d’exécution externe + une couche de lecture et de debug.

Le vrai problème que cette architecture résout

Sans cette architecture, une application distribuée doit gérer elle-même :

• l’état courant d’une orchestration ;
• les retries cohérents ;
• les réveils à retardement ;
• la reprise après crash ;
• la relecture de l’historique ;
• la distribution des tâches aux bons exécutants.

Le dépôt insiste sur cette idée dès le début de la série : si vous avez juste une requête HTTP courte ou un simple fire-and-forget, Temporal est probablement excessif. En revanche, si vous avez un traitement long, multi-étapes, qui doit rester fiable après panne, alors l’architecture du cluster devient la pièce centrale du système.

Le service History existe justement pour cela : appliquer les transitions d’état, écrire les événements, posséder les timers et alimenter les files internes. Ce n’est pas un détail d’implémentation, c’est le cœur du contrat de fiabilité.

Le modèle mental minimal

Voici le raccourci le plus utile pour ne pas se tromper quand on débute avec Temporal :

Brique	Rôle principal	Ce qu’il ne faut pas confondre
Frontend	expose l’API gRPC publique	ce n’est pas le moteur d’exécution de votre code
History	conserve l’état durable et l’historique	ce n’est pas juste une base de données passive
Matching	remet les tâches aux pollers	ce n’est pas une simple queue métier visible telle quelle
Worker interne	gère des traitements système Temporal	ce n’est pas votre worker Python applicatif
Visibility	permet de lister, filtrer, rechercher	ce n’est pas la source d’autorité pour l’exécution
vos workers	exécutent workflows et activities	ils ne sont pas hébergés dans le serveur Temporal

Cette séparation est explicite dans 02-architecture-overview/slides.md, puis renforcée dans 04-installation-and-dev-server/slides.md et dans les chapitres de déploiement plus loin dans la série.

Les briques internes du serveur Temporal

Frontend

Le slide deck indique que Frontend est l’API gRPC publique sur le port 7233. C’est par là que passent :

• les clients ;
• la CLI ;
• la Web UI ;
• les workers.

Quand un worker Python se connecte avec Client.connect("localhost:7233"), il ne parle pas directement à un workflow. Il parle d’abord au service Frontend, qui route ensuite la requête vers le bon service interne.

History

History est présenté comme le cœur durable du moteur. Il :

• applique les transitions d’état des workflows ;
• écrit les événements dans l’historique ;
• possède les timers ;
• alimente des files asynchrones internes.

Si vous cherchez la partie vraiment spécifique à Temporal, c’est ici. C’est aussi la raison pour laquelle l’historique d’exécution devient un objet central dans toute la suite de la série.

Matching

Matching est le service de distribution des tâches. Il reçoit les polls des workers et leur remet :

• les workflow tasks ;
• les activity tasks.

Cette couche explique pourquoi, du point de vue développeur, on travaille avec une task queue logique alors que la plateforme peut partitionner et distribuer la charge en interne.

Worker interne

Le chapitre 02 rappelle qu’il existe aussi un Worker interne au cluster. Il ne faut pas le confondre avec vos processus applicatifs. Ce composant sert aux workflows système et aux tâches de maintenance de Temporal lui-même.

Visibility

La couche Visibility est décrite comme un read model séparé pour lister et rechercher les workflows. Le slide deck ajoute qu’en self-hosted elle est souvent associée à Elasticsearch pour la recherche avancée.

C’est important : la lecture optimisée pour la Web UI et les recherches n’est pas le même problème que l’orchestration durable des transitions d’état.

Ce qui scale horizontalement dans Temporal

Le point fort du chapitre est de ne pas rester au niveau liste de composants. Il montre aussi les unités de scalabilité :

• les History shards, unités de possession des exécutions de workflow ;
• les Matching partitions, unités de scalabilité de la distribution des tâches ;
• les files par shard, comme transfer, timer, visibility, replication, archival ;
• les worker pollers, qui restent un levier côté client.

Concrètement, le dépôt explique qu’un workflow run est hashé vers un shard d’historique. Ce shard garde l’état mutable et la cohérence de son historique. De l’autre côté, une même task queue logique peut être répartie sur plusieurs partitions internes de matching, alors que les workers continuent de poller le même nom de queue.

Cette séparation entre état durable et distribution des tâches est l’une des clés de lecture les plus utiles pour comprendre pourquoi Temporal tient la charge sans vous obliger à coder vous-même la coordination.

Persistance, Web UI et SDK Python

Persistance

Le chapitre 02-architecture-overview/slides.md énumère clairement les options de persistance :

• SQLite pour le dev local ;
• PostgreSQL pour un setup simple et durable ;
• MySQL ;
• Cassandra pour un modèle historiquement horizontal ;
• Elasticsearch en option pour la visibilité avancée.

Le chapitre 04-installation-and-dev-server/slides.md précise que temporal server start-dev utilise SQLite en mémoire par défaut. Plus loin, 04-installation-and-dev-server/notes-docker-compose.md montre un stack Compose avec PostgreSQL, et 33-self-hosted-deployment/slides.md confirme le pattern Kubernetes avec base externe et chart Helm.

Web UI

Le repo insiste beaucoup sur la Web UI, et c’est justifié. Dans 02-architecture-overview/slides.md, elle est présentée comme :

• la liste des workflows en cours, terminés ou en erreur ;
• l’accès à l’historique complet d’une exécution ;
• la visualisation des stack traces de workflows bloqués ;
• l’accès aux schedules, task queues et namespaces ;
• un point d’entrée pour envoyer des signaux ou annuler des exécutions.

Le slide va jusqu’à la qualifier d’outil de debug numéro 1. C’est cohérent avec le reste de la série : dès qu’on commence à lancer de vrais workflows, l’historique et la lecture des états deviennent indispensables.

Où se place le SDK ?

Le point pédagogique le plus important de l’épisode est probablement celui-ci : le SDK vit dans votre processus, pas dans le serveur Temporal.

Le chapitre formule cela très clairement :

• le SDK ouvre une connexion gRPC vers le serveur ;
• il poll les task queues ;
• il exécute votre code de workflow et d’activity.

Et surtout :

• le serveur Temporal ne fait pas tourner votre code applicatif ;
• il stocke l’historique et distribue les tâches ;
• votre code s’exécute là où vous avez démarré le worker.

C’est la phrase qu’il faut garder en tête avant d’aborder les chapitres 05-hello-world et 06-running-with-temporal-cli.

Quelle forme de déploiement choisir ?

Le chapitre 02 liste quatre formes de déploiement, et les chapitres suivants les concrétisent. Voici la lecture la plus utile :

Forme	Ce que montre le dépôt	Quand c’est adapté
temporal server start-dev	04-installation-and-dev-server/slides.md	apprentissage, démos, CI locale, tests rapides
Docker Compose	04-installation-and-dev-server/notes-docker-compose.md	lab local plus réaliste avec Postgres et UI séparée
Kubernetes Helm	33-self-hosted-deployment/slides.md	cluster self-hosted avec services séparés et base externe
Temporal Cloud	33-self-hosted-deployment/slides.md	quand on veut externaliser le control plane et ne garder que les workers

Quelques repères concrets issus du dépôt :

• en local, start-dev expose gRPC sur 7233 et la Web UI sur 8233 ;
• en Docker Compose, la note associe gRPC à 7233 et la Web UI à 8080 ;
• en Kubernetes via Helm, les 4 services du serveur plus la Web UI sont installés, avec une base que vous fournissez vous-même.

Premier setup et commandes utiles

Le README.md et le chapitre 04-installation-and-dev-server donnent déjà les premières commandes réalistes à mémoriser :

# lancer un serveur de dev Temporal
temporal server start-dev

# lancer un worker de démo
uv run 05-hello-world/worker.py

# lancer le workflow depuis un autre terminal
uv run 05-hello-world/starter.py

Une fois le serveur lancé, les repères de base restent les mêmes :

# vérifier les namespaces disponibles
temporal operator namespace list

# ouvrir la Web UI en dev local
open http://localhost:8233

Ces commandes ne viennent pas d’une doc externe inventée : elles sont alignées sur le README.md du dépôt et sur 04-installation-and-dev-server/slides.md.

Liens utiles

• Dépôt GitLab : xavki/temporal-tutorials
• README du dépôt : README.md
• Chapitre source : 02-architecture-overview/slides.md
• Chapitre installation : 04-installation-and-dev-server/slides.md
• Note Docker Compose : 04-installation-and-dev-server/notes-docker-compose.md
• Chapitre self-hosted / Helm : 33-self-hosted-deployment/slides.md
• Documentation officielle Temporal : docs.temporal.io
• Documentation CLI : docs.temporal.io/cli
• SDK Python : python.temporal.io
• Docker Compose officiel Temporal : github.com/temporalio/docker-compose
• Helm charts officiels Temporal : github.com/temporalio/helm-charts
• Vidéo YouTube : Temporal – 02. Architecture d’un cluster
• Playlist : Temporal – Tutorials

FAQ

Temporal exécute-t-il mon code dans le cluster ?

Non. Le chapitre 02 explique explicitement que le serveur stocke l’historique et distribue les tâches, tandis que votre code s’exécute dans vos propres workers.

À quoi sert le service Frontend ?

Frontend est l’entrée publique gRPC. Clients, CLI, Web UI et workers passent par lui avant que la requête soit routée vers les services internes appropriés.

Quelle est la différence entre History et Visibility ?

History gère l’état durable et les événements d’exécution. Visibility sert plutôt à lire, lister et rechercher les workflows via une vue adaptée à la consultation.

Pourquoi la Web UI est-elle si importante ?

Parce qu’elle permet de voir l’historique complet d’une exécution, de comprendre un blocage, de lister les workflows, et d’interagir avec certaines exécutions. Le dépôt la présente comme l’outil de debug principal.

Quelle base utiliser pour commencer ?

Pour apprendre, le dépôt recommande le dev server avec SQLite. Pour un setup plus durable, les chapitres déploiement montrent PostgreSQL, MySQL ou Cassandra, avec Elasticsearch en option pour la visibilité avancée.

Faut-il commencer par Kubernetes pour apprendre Temporal ?

Non. Le fil pédagogique du dépôt est clair : d’abord start-dev, puis les notions, puis le Hello World, puis les patterns de déploiement plus avancés.

Conclusion

Ce deuxième chapitre est court, mais il pose la bonne carte mentale pour toute la suite de la série. Si vous comprenez déjà que :

• le serveur Temporal orchestre et persiste ;
• les workers exécutent votre code ;
• Frontend, History et Matching ont des rôles distincts ;
• la Web UI est votre point d’observation privilégié,

alors vous aborderez les chapitres suivants avec beaucoup moins de confusion.

Le plus utile dans ce dépôt, c’est que cette architecture n’est pas décrite de façon abstraite : elle est reliée à un chemin d’apprentissage concret, depuis 01-introduction, puis 02-architecture-overview, jusqu’à 04-installation-and-dev-server, 05-hello-world et les chapitres de déploiement self-hosted.

Si vous suivez la série dans l’ordre, ce chapitre est exactement le bon moment pour fixer une idée simple et durable : Temporal n’est pas juste une queue ou un moteur de jobs. C’est une architecture d’orchestration fiable, observée, persistante, et pensée pour les traitements qui doivent survivre au monde réel.