Architecture Governance
Statut
Document fondateur — v1.0 — rédigé le 2026-07-19.
Ce document ferme officiellement la phase de conception architecturale de DMV et ouvre la phase d'exécution, fondée sur les ADR et les Work Packages.
Il ne décrit plus ce qu'est l'architecture de DMV — c'est le rôle de 26-platform-architecture.md. Il décrit comment elle est autorisée à évoluer, et par quel processus toute personne, humaine ou non, doit passer avant d'y toucher.
Chapitre 1 — Les fondations
Quatre niveaux de texte gouvernent DMV, et ils ne changent pas à la même vitesse.
La Vision change très rarement — une fois tous les plusieurs années, à l'occasion d'un changement de doctrine, pas d'un changement de marché ou de technologie.
L'Architecture change exceptionnellement — lorsqu'une responsabilité entière doit être déplacée d'une couche à une autre, ou qu'une nouvelle couche doit apparaître.
Les ADR figent les décisions. Une fois un ADR accepté, il n'est jamais réécrit pour changer son sens : une décision qui change produit un nouvel ADR, qui remplace explicitement l'ancien.
Les Work Packages implémentent ces décisions. Ils traduisent une décision déjà prise en travail concret, borné, livrable.
Une règle domine toutes les autres : le code n'est jamais la source de vérité. Le code est une implémentation, à un instant donné, d'une décision documentée ailleurs. Lorsque le code et la documentation divergent, ce n'est jamais le code qui a raison par défaut — c'est un signal qu'une décision doit être prise pour résoudre l'écart (voir Chapitre 8).
La documentation architecturale reste la référence, y compris lorsqu'elle décrit une cible pas encore atteinte par le code. Un document qui décrit une cible non livrée n'est pas faux — il est en avance sur son implémentation, ce qui est une situation normale et attendue, tant que l'écart reste identifié comme tel.
Chapitre 2 — Les niveaux de stabilité
Tout ce qui compose DMV n'a pas vocation à changer à la même fréquence. Confondre les niveaux de stabilité est la cause la plus fréquente de dégradation progressive d'une architecture.
Très stables — Vision, Principes, Architecture globale (les couches et le sens des dépendances définis dans 26-platform-architecture.md).
Ces éléments sont très stables parce que tout le reste de la plateforme est construit en tenant leur vérité pour acquise. Les remettre en cause revient à remettre en cause tout ce qui a été construit dessus — leur coût de changement est donc, par construction, le plus élevé de la plateforme.
Stables — Engines, Platform Services.
Ces éléments changent, mais uniquement à l'occasion d'une décision explicite (un ADR). Un Engine ou un Platform Service représente une responsabilité déjà négociée et documentée ; plusieurs applications et d'autres composants en dépendent. Un changement non gouverné à ce niveau se répercute silencieusement sur tout ce qui en dépend.
Évolutifs — Implémentations, Frameworks, Technologies.
Ces éléments peuvent changer sans ADR, tant que le changement reste invisible depuis les couches supérieures — c'est-à-dire tant qu'il ne modifie ni la responsabilité portée, ni le contrat exposé aux couches qui en dépendent. Remplacer une technologie par une autre pour exécuter la même responsabilité, exactement de la même façon vue de l'extérieur, est un changement évolutif, pas architectural.
Très évolutifs — UI, UX, Design, Fonctionnalités.
Ces éléments changent en continu, au rythme du produit, sans gouvernance architecturale — c'est précisément leur rôle. Une architecture qui ralentit ce niveau a échoué à protéger ce qui devait rester rapide à faire évoluer.
Un élément peut migrer d'un niveau à l'autre. Une implémentation qui devient une convention utilisée partout, de façon informelle, doit être formalisée en Platform Service via un ADR plutôt que de rester une pratique tacite — sans quoi elle devient une dépendance stable non gouvernée, ce qui est le pire des deux mondes.
Chapitre 3 — Comment une évolution est décidée
Nouveau besoin
↓
Analyse
↓
Décision architecturale
↓
ADR
↓
Documentation
↓
Work Package
↓
Développement
↓
Validation
↓
Merge
Chaque étape a un rôle précis :
- Nouveau besoin — exprimé sans présumer de sa solution technique.
- Analyse — détermine si le besoin peut être satisfait par une responsabilité déjà existante (voir Chapitre 4), ou s'il exige un changement de structure.
- Décision architecturale — ne se prend que si l'analyse conclut à un changement de structure : une nouvelle responsabilité, un déplacement entre couches, un changement de niveau de stabilité (Chapitre 2).
- ADR — enregistre la décision dans le registre canonique du projet (
docs/decisions/), selon le format déjà en vigueur (Statut, Date, Contexte, Décision, Conséquences, Alternatives envisagées, Risques, Liens associés). Un ADR n'est jamais informel ni implicite. - Documentation — les documents d'architecture concernés (couche, Engine, Platform Service) sont mis à jour pour refléter la décision, avant que le développement ne commence.
- Work Package — traduit la décision en travail borné et livrable.
- Développement, Validation, Merge — exécution normale, inchangée par ce document.
Règle non négociable : le développement ne doit jamais précéder la décision architecturale lorsqu'un changement de structure est nécessaire. Un Work Package peut démarrer directement à l'étape « Nouveau besoin → Work Package » uniquement lorsque l'Analyse conclut que la responsabilité existe déjà et n'a pas besoin de changer — c'est-à-dire lorsque le besoin se résout entièrement à l'intérieur des niveaux Évolutifs ou Très évolutifs.
Sur le registre des ADR. Le registre canonique des décisions d'architecture de DMV est docs/decisions/ (numérotation séquentielle globale, ADR-001 et suivants). Certains documents de domaine, rédigés avant que ce registre ne soit systématiquement utilisé, contiennent leur propre liste locale de décisions sous une numérotation « ADR-XXX » qui leur est propre (c'est le cas de la documentation mobile). Ces listes locales restent valables comme historique, mais toute nouvelle décision structurante, quel que soit le domaine qu'elle concerne, doit désormais être enregistrée dans le registre canonique — jamais dans une nouvelle numérotation locale.
Chapitre 4 — Création d'un nouveau composant
Avant de créer un nouveau composant, la question n'est jamais « quelle technologie dois-je utiliser ? ». Elle est toujours, dans cet ordre :
- Ce besoin est-il déjà couvert par une Application existante, qui peut simplement composer différemment ce qui existe déjà ?
- Ce besoin est-il déjà couvert par un Engine existant, dont la responsabilité s'étend naturellement à ce cas ?
- Ce besoin est-il déjà couvert par un Platform Service existant, capable d'exécuter cette capacité technique sans décision métier ajoutée ?
- Ce besoin est-il déjà couvert par l'Infrastructure existante, sans capacité technique nouvelle à fournir ?
Un nouveau composant n'est créé que si aucune des quatre réponses n'est oui — et il est alors positionné dans la couche qui correspond à sa nature réelle (décide-t-il, exécute-t-il, fournit-il, compose-t-il ? — voir 26-platform-architecture.md, Chapitre 4), jamais dans la couche la plus pratique à court terme.
Un besoin qui semble nouveau est, la plupart du temps, une variation d'une responsabilité déjà décidée. Étendre un Engine ou un Platform Service existant pour couvrir un cas voisin est presque toujours préférable à la création d'un nouveau composant parallèle — la duplication de responsabilités est une dette architecturale (Chapitre 8), pas une solution rapide.
Chapitre 5 — Dépendances
Ne jamais dépendre d'une technologie. Dépendre d'une responsabilité.
Un composant qui a besoin de stocker une donnée dépend du Platform Service Storage, jamais directement d'une base de données particulière. Un composant qui a besoin de naviguer dépend du Platform Service Navigation, jamais directement d'un framework de routage. La technologie qui implémente une responsabilité peut être remplacée sans qu'aucun composant dépendant n'ait à changer, tant que la responsabilité elle-même reste stable.
Préférer les abstractions.
Une abstraction bien posée coûte plus cher à écrire au premier jour et coûte moins cher à chaque jour suivant. Une dépendance directe à une technologie coûte moins cher au premier jour et plus cher à chaque remplacement futur — DMV choisit systématiquement le second coût plutôt que le premier.
Limiter les dépendances.
Chaque dépendance ajoutée entre deux composants est un engagement à maintenir leur compatibilité dans le temps. Un composant qui dépend de peu de choses est plus facile à faire évoluer, à tester et à remplacer qu'un composant qui dépend de beaucoup de choses, même si chacune de ces dépendances est individuellement justifiée.
Éviter les cycles.
Deux composants qui dépendent l'un de l'autre ne peuvent plus évoluer indépendamment — c'est l'inverse de l'objectif d'une architecture en couches. Lorsqu'un cycle apparaît entre deux Engines, ou entre un Engine et un Platform Service, c'est le signe que la responsabilité de l'un des deux est mal délimitée, jamais une situation à contourner par un ajustement technique local.
Chapitre 6 — Documentation
Vision
↓
Architecture
↓
ADR
↓
Work Packages
↓
Code
Le code implémente la documentation. Jamais l'inverse.
Cette règle a une conséquence directe sur ce qu'il faut faire lorsque le code et la documentation ne correspondent plus : la documentation ne « gagne » pas non plus automatiquement. Un écart entre le code et la documentation est un signal à traiter, pas un verdict déjà rendu. Il se résout de deux façons, jamais en le laissant sans réponse :
- si le comportement réel du code s'avère être le bon choix, la documentation est mise à jour — au besoin via un nouvel ADR si l'écart touche une décision de structure ;
- si le comportement du code s'est écarté par erreur ou par raccourci, le code est corrigé pour rejoindre la décision documentée.
Laisser cet écart sans le trancher est la définition même d'une dette architecturale non traitée (Chapitre 8).
Chapitre 7 — Évolution de la plateforme
Les Applications évolueront. Les Platform Services évolueront. Les Engines évolueront. L'Infrastructure changera, probablement plusieurs fois, au fil des années.
Ce qui doit rester stable, indépendamment de tout ce qui précède, ce sont les principes eux-mêmes : le sens des dépendances entre couches, la distinction entre décider, exécuter, fournir et composer, les niveaux de stabilité de ce chapitre, et le processus de décision du Chapitre 3.
Une plateforme qui a besoin de revoir ses principes à chaque changement de technologie n'avait pas de principes — elle avait des habitudes. DMV vise l'inverse : que la disparition de n'importe quelle technologie citée dans sa documentation d'architecture ne remette jamais en cause un seul principe de gouvernance.
Chapitre 8 — Dette technique
Trois natures de dette existent à DMV, et elles ne se traitent pas de la même façon.
Dette technique acceptable. Un raccourci pris consciemment, à l'intérieur d'une responsabilité déjà décidée, sans violer aucune règle de dépendance entre couches. Elle ne dégrade jamais l'architecture — seulement, localement, la qualité de son implémentation. Elle peut rester en l'état tant qu'elle ne gêne personne.
Dette technique temporaire. Un raccourci pris consciemment, avec une échéance ou une condition de résorption explicite, généralement documentée dans le Work Package ou l'ADR qui l'a introduite. Une version bêta qui réutilise volontairement une architecture existante et reporte explicitement des composants cibles à une version ultérieure en est un exemple direct — la dette existe, elle est nommée, elle a une date ou une condition de fin.
Dette architecturale. Une violation d'une règle de dépendance entre couches — une Application qui dépend directement d'une technologie d'infrastructure, un Platform Service qui contient une décision métier, un cycle entre deux composants. Ce n'est jamais une question de qualité de code : c'est une fissure dans la structure elle-même.
Une dette architecturale doit être traitée rapidement. Elle ne se stabilise jamais d'elle-même — chaque composant supplémentaire construit par-dessus la rend plus coûteuse à corriger, parce qu'il faudra ensuite migrer non seulement la violation initiale, mais tout ce qui s'y est appuyé depuis. Une dette technique, en revanche, peut être planifiée : elle ne grandit pas nécessairement avec le temps, et son coût de correction reste globalement stable qu'elle soit traitée aujourd'hui ou dans six mois.
Le test pour distinguer les deux est simple : la dette reste-t-elle strictement à l'intérieur d'une responsabilité déjà décidée ? Alors c'est une dette technique. Traverse-t-elle une frontière que l'architecture interdit de traverser ? Alors c'est une dette architecturale, et elle doit produire un ADR — soit pour la corriger, soit, si elle révèle que la règle elle-même doit changer, pour acter ce changement explicitement plutôt que de le laisser s'installer par défaut.
Chapitre 9 — Philosophie DMV
Construire des abstractions avant des implémentations : une responsabilité bien nommée survit au remplacement de sa technologie ; une implémentation sans abstraction devient elle-même la seule documentation de ce qu'elle est censée faire.
Privilégier les responsabilités aux technologies : DMV ne dépend jamais d'un outil, toujours d'un rôle que cet outil remplit temporairement.
Une bonne architecture rend les changements moins coûteux, pas moins nombreux. L'objectif n'est jamais de figer la plateforme — c'est de garantir que chaque changement futur coûte ce qu'il devrait coûter, jamais plus, à cause d'une dépendance mal placée aujourd'hui.
L'architecture est un investissement, pas une contrainte. Le temps passé à décider où placer une responsabilité avant de l'implémenter n'est jamais du temps perdu sur la vitesse de développement — c'est le temps qui évite de le reperdre, plus tard, à démêler ce qui n'aurait jamais dû être mélangé.
Conclusion
Ce document ferme la phase de conception architecturale de DMV.
Ce qui a été défini — les couches, les responsabilités, les dépendances autorisées — ne se rediscute plus au fil de chaque Work Package. Ce qui reste ouvert, et le restera toujours, c'est la façon dont cette architecture est autorisée à évoluer : par l'analyse d'un besoin réel, par une décision explicite lorsqu'elle touche une structure, par un ADR qui la fige, par une documentation qui la reflète, et par un Work Package qui, seulement alors, la met en œuvre.
À partir de ce document, DMV entre dans sa phase d'exécution.