ADR-0003 : Découpage en services par contexte métier
| Statut | Accepté |
| Date | 2025-10 |
| Décideurs | Équipe de développement Edukit |
| Périmètre | Plateforme (OrgService, VmService, Worker) |
Contexte
Edukit doit couvrir deux familles de responsabilités très différentes :
- la gestion organisationnelle (établissements, utilisateurs, groupes, environnements de travail, séances, licences) : opérations courtes, transactionnelles, fortement liées à Keycloak et à un schéma relationnel ;
- le provisionnement Proxmox : opérations longues (environ 3 minutes par VM), faillibles, dépendantes d’un système externe peu fiable, à propager en temps réel et à mettre à l’échelle indépendamment lors des pics de début de séance.
Mettre ces deux familles dans un seul processus poserait des problèmes concrets : un incident du provisionnement (Proxmox indisponible, saga bloquée) ne doit pas faire tomber la gestion des utilisateurs ; et seule la partie provisionnement a besoin de monter en charge. À l’inverse, multiplier les microservices au-delà du nécessaire introduirait du coût opérationnel (déploiement, observabilité, cohérence des données) sans bénéfice pour un projet de cette taille.
Décision
Découper la plateforme en deux services applicatifs alignés sur deux contextes métier délimités, plus une séparation interne au sein du service de provisionnement :
Edukit-OrgService: contexte organisationnel. API REST (port 5100) plus serveur gRPC (port 5101). Base PostgreSQLorgservice.Edukit-VM: contexte provisionnement, lui-même scindé en deux processus :- une API (port 5200, gRPC 5201) qui accepte les commandes, répond immédiatement en
202 Acceptedet diffuse les transitions via SignalR ; - un Worker (port de sonde 5300, sans point d’entrée applicatif) qui exécute les sagas longues contre Proxmox.
Les deux processus partagent la base
vmserviceet le courtier RabbitMQ.- une API (port 5200, gRPC 5201) qui accepte les commandes, répond immédiatement en
L’infrastructure reste mutualisée et non redondante (un seul RabbitMQ, une seule instance PostgreSQL hébergeant plusieurs bases, un seul royaume Keycloak), conformément aux choix d’éco-conception.
Conséquences
Bénéfices
- Isolation des pannes : une saga Proxmox bloquée n’affecte pas la gestion des utilisateurs.
- Mise à l’échelle ciblée : seul le
Workerde VmService est dimensionné pour absorber les pics de provisionnement (voir ADR-0004 et le partitionnement RabbitMQ). - Découplage du chemin de réponse HTTP des opérations longues : l’API répond en
202 Acceptedsans attendre les 3 minutes de provisionnement ; le suivi passe par SignalR. - Indépendance de déploiement : chaque service a ses propres chaînes CI / CD et son propre cycle de version.
Coûts et limites
- Cohérence inter-services à gérer explicitement : pas de transaction distribuée entre OrgService et VmService. Les flux qui les traversent (transmission des identifiants de VM jusqu’au courriel étudiant) reposent sur la messagerie asynchrone et des patrons de compensation.
- Communication réseau entre services : choisie en gRPC pour limiter le surcoût (voir ADR-0007).
- Surface opérationnelle plus large que pour un monolithe : compensée par la mutualisation de l’infrastructure et par l’observabilité OpenTelemetry unifiée.
Alternatives écartées
- Monolithe modulaire unique : plus simple à déployer et à rendre cohérent, mais couplerait le cycle de vie du provisionnement long à celui de la gestion organisationnelle, et empêcherait la mise à l’échelle ciblée du seul provisionnement. Écarté pour l’isolation des pannes et la scalabilité différenciée.
- Découpage plus fin (un microservice par entité : utilisateurs, groupes, licences, etc.) : surdimensionné pour la taille de l’équipe et du domaine ; multiplierait les transactions distribuées et le coût opérationnel sans bénéfice.
- API et Worker dans le même processus pour VmService : exposerait le chemin HTTP aux blocages des opérations longues et empêcherait de mettre à l’échelle le seul traitement de saga. La séparation API / Worker a été retenue à la place.