Le document d'architecture : de l'étude de cas au livrable

Le permis, puis le dossier des ouvrages exécutés

Sur Le Chantier, rien ne sort de terre avant le permis de construire. Le dossier décrit ce qu'on va bâtir, sur quelle emprise, avec quelles hauteurs et quelles contraintes. Il engage tout le monde en même temps : le maître d'ouvrage qui paie, l'architecte qui conçoit, les entreprises qui exécutent.

À la réception du bâtiment arrive un second dossier, le DOE, dossier des ouvrages exécutés. Celui-là ne dit plus ce qu'on voulait faire, il dit ce qui a réellement été construit : les plans à jour, les matériaux posés, le tracé effectif des réseaux. C'est le document qu'on ressort quinze ans plus tard, quand il faut percer un mur sans couper une gaine.

Le document d'architecture logicielle joue les deux rôles à la fois. Il engage avant, il documente après, et c'est le seul livrable que l'architecte produit vraiment de sa main.

D'où la règle qui fâche : pas une ligne de code avant que le document existe et qu'il ait été lu. Pas relu, pas approuvé en réunion, simplement lu par ceux qui vont écrire le code.

Un document d'architecture qui arrive après le développement n'est pas un document d'architecture. C'est un compte rendu, et personne n'a besoin d'un compte rendu.

L'objection classique tombe toujours au même endroit : « on n'a pas le temps ». La réponse tient en une observation de chantier. Le temps passé à écrire le document est sans commune mesure avec le temps passé à démolir un plancher mal placé.

Ce billet se lit en deux temps. D'abord la structure du livrable : cinq sections, chacune avec sa longueur et son lectorat, plus une question de format que tout le monde tranche mal. Ensuite une étude de cas complète, qui déroule sur un système réel tout ce que la série a posé depuis le premier billet, de la première question au client jusqu'au tableau de conformité aux exigences.

Les cinq sections du document

Un dossier de permis n'est pas un tas de plans. Il a un ordre imposé, parce que l'instructeur qui le lit doit trouver chaque pièce à sa place. Le document d'architecture fonctionne pareil, et cinq sections suffisent.

Elles ne s'adressent pas au même monde, et c'est le point que l'on rate le plus souvent. Une direction générale, un chef de projet et un développeur ne cherchent pas la même chose dans le même fichier. Écrire pour tout le monde en même temps, c'est n'être lu par personne.

L'ordre d'écriture n'est pas l'ordre de lecture, et c'est voulu. On écrit du contexte vers le détail, parce que chaque section s'appuie sur la précédente. On lit à partir du résumé exécutif, parce que le premier lecteur est presque toujours celui qui décide.

Le document a un ordre d'écriture et un ordre de lecture, et ils sont inverses. Le résumé exécutif se rédige en dernier parce qu'il résume quelque chose qui n'existe pas encore quand on commence.

Le contexte : le système vu du métier

La notice qui ouvre un dossier de permis ne parle ni de ferraillage ni de descente de charges. Elle explique en langage courant ce que le bâtiment doit permettre : loger soixante familles, accueillir quatre commerces en rez-de-chaussée, garer cent véhicules.

La section contexte fait exactement ça. Une page qui décrit le système du point de vue de celui qui va s'en servir, sans un seul terme technique. Si le texte contient le mot « cache » ou le mot « conteneur », il n'est pas au bon endroit.

Le test est simple : quelqu'un qui découvre le projet doit pouvoir expliquer à voix haute, après cette page, à quoi sert ce qu'on va construire. Pas comment. À quoi.

Cette section a une seconde utilité, moins évidente. Elle fixe le vocabulaire. Si l'entreprise dit « site » là où l'équipe dit « établissement », le désaccord se règle ici, sur une page, plutôt que trois mois plus tard dans un schéma de base de données.

Le contexte n'est pas une introduction de politesse. C'est le lexique commun du projet, et le seul endroit du document où le métier a le dernier mot sur les mots.

Les exigences : le programme et l'étude de sol

Deux natures d'exigences cohabitent, et la série les a séparées dès le billet sur le processus d'architecture. Le programme dit ce que le bâtiment doit permettre de faire, l'étude de sol dit à quoi il devra faire face.

Les exigences fonctionnelles viennent d'abord, en liste. Trois lignes maximum par exigence, verbe à l'indicatif, un identifiant devant. Pas de récit, pas de justification, pas de « il serait souhaitable que ».

Les exigences non-fonctionnelles viennent ensuite, et elles portent des chiffres. Une exigence non-fonctionnelle sans chiffre n'est pas une exigence, c'est un vœu. « Rapide » ne se recette pas, « 300 ms au 95e centile sur la route de consultation » se recette.

Une précision utile sur le rôle de cette section. Le document d'architecture ne remplace pas le cahier des charges : il en recopie les exigences en version courte, parce que chaque décision technique devra pouvoir pointer vers l'une d'elles.

C'est ce chaînage qui donne au document sa force en réunion. Face à un « pourquoi une file de messages et pas un appel direct », on répond par une ligne du tableau des exigences plutôt que par une préférence personnelle.

Toute décision d'architecture qui ne se rattache à aucune exigence est une décision gratuite. Elle finira par coûter quelque chose à quelqu'un.

Le résumé exécutif : écrit en dernier, lu en premier

Le maître d'ouvrage ne lit pas les plans de coffrage. Il lit la note qui dit : voilà ce que vous obtenez, voilà le délai, voilà ce qui peut déraper. C'est sur cette note qu'il signe.

Le résumé exécutif s'écrit pour ce lecteur-là, et pour lui seul. Une page, jamais deux. Aucun schéma. Aucun nom de produit, sauf s'il implique un achat.

Trois choses y figurent. Ce que le système fera, en trois ou quatre phrases reprises du contexte. Les deux ou trois décisions structurantes, celles qui coûtent cher à défaire. Et les risques identifiés, avec ce qu'on propose d'en faire.

Le piège est de le rédiger en premier, quand on croit encore savoir ce qu'on va construire. Le contenu ne devient juste qu'une fois le détail par composant terminé, parce que c'est en descendant dans le détail qu'on découvre les vrais points durs.

Un repère fiable : si le résumé exécutif ne contient aucun risque, il est incomplet. Un projet sans risque est un projet dont personne n'a encore regardé les hypothèses de charge.

Cette page est souvent la seule que la direction lira. Si elle est mauvaise, le reste du document n'existe pas, quelle que soit sa qualité.

La vue d'ensemble : un schéma et sa lecture commentée

Le plan de masse du permis tient sur une feuille. Il montre les bâtiments, les voiries, les raccordements aux réseaux publics, et rien d'autre. Il ne dit pas où passent les prises électriques.

La vue d'ensemble de l'architecture fonctionne au même niveau de zoom. Un schéma, les composants majeurs, les flux entre eux, les magasins de données. Une quinzaine de boîtes au maximum, au-delà personne ne suit.

Le schéma seul ne suffit jamais. Il faut sa lecture commentée : un paragraphe qui déroule le parcours d'une requête typique de bout en bout, en nommant chaque boîte traversée dans l'ordre.

Cette lecture commentée est la partie que les architectes sautent le plus volontiers, et c'est la plus lue. Un développeur qui arrive sur le projet comprend un système en suivant un flux, pas en contemplant un diagramme.

Il faut aussi documenter ce qui n'est pas sur le schéma. Un service externe volontairement laissé hors périmètre, une brique existante qu'on réutilise sans la modifier : dire explicitement qu'on ne l'a pas oubliée évite trois réunions.

Un schéma d'architecture sans texte se prête à autant d'interprétations qu'il a de lecteurs. Le commentaire n'est pas un supplément, c'est la moitié de la section.

Le détail par composant

On descend d'un cran, au niveau du gros œuvre : ce que chaque lot doit construire, avec quels matériaux, et selon quelles règles de l'art. Chaque composant identifié dans la vue d'ensemble obtient sa propre sous-section, et toutes suivent le même gabarit.

Le rôle, en deux phrases. Ce que fait le composant, et surtout ce qu'il ne fait pas. La seconde moitié évite les débordements de responsabilité qui transforment un service en fourre-tout.

La stack et sa justification. Pas seulement le nom de la technologie, mais la raison. Une stack sans justification écrite se fait rediscuter à chaque arrivée dans l'équipe, indéfiniment.

L'architecture interne. Les couches du composant, ce que chacune contient, et le sens autorisé des dépendances. C'est le niveau où l'on retrouve l'interface de service, la logique métier et l'accès aux données posés au palier 2 de la série.

Les consignes de développement. Conventions de nommage, politique de gestion des exceptions, ce qui doit être journalisé et à quel niveau, ce qui est attendu en tests. Court, impératif, non négociable. L'objectif n'est pas d'avoir raison sur le camelCase, il est d'éviter que quatre développeurs tranchent quatre fois différemment.

Le contrat exposé, enfin, pour tout composant que d'autres appellent. Une API se décrit au niveau de la route, du verbe, du corps attendu et des codes de retour. Pas au niveau du code. Le tableau ci-dessous en donne un exemple, repris de la plateforme qui sert d'étude de cas plus bas.

Le niveau de détail attendu se règle sur une question unique : un développeur qui n'a pas participé à la conception peut-il commencer à coder avec ça ? Si la réponse est non, il manque quelque chose. Si le document contient des noms de variables, il y a trop de choses.

Le détail par composant n'a pas à décrire l'implémentation. Il doit rendre l'implémentation possible sans réunion supplémentaire.

Sur le format : pourquoi pas d'UML ici

L'architecte du bâtiment a des conventions de dessin normalisées, et il les utilise avec les entreprises. Il n'envoie pas une coupe cotée au maître d'ouvrage pour lui expliquer où sera l'entrée.

UML existe, la spécification est publiée par l'OMG et elle est précise. Elle est aussi volumineuse, et elle suppose que l'auteur comme le lecteur en maîtrisent le vocabulaire graphique.

Dans un document d'architecture destiné à des lecteurs mélangés, cette hypothèse est fausse la plupart du temps. Un diagramme de séquence UML lu par quelqu'un qui n'en connaît pas les règles produit une compréhension approximative, ce qui est pire qu'une compréhension absente.

Ce qu'on fait à la place tient en trois règles. Des boîtes et des flèches, avec une légende explicite pour chaque forme et chaque type de trait. Un seul niveau de zoom par schéma. Et des tableaux partout où l'information est comparative, parce qu'un tableau se lit sans apprentissage.

Deux références aident à structurer sans imposer une notation formelle. Le modèle C4 propose quatre niveaux de zoom emboîtés, du contexte système jusqu'au code, ce qui donne une discipline simple pour ne pas mélanger les échelles. Le gabarit arc42 fournit une trame de douze sections, dont on peut ne retenir que celles qui servent.

La bonne notation est celle que ton lecteur sait lire sans formation préalable. Tout le reste est de la précision qui ne circule pas.

Les ADR : ce que le document figé ne sait pas garder

Entre le permis déposé et le DOE remis, il se passe deux ans de chantier. Pendant ces deux ans, des arbitrages tombent en réunion hebdomadaire : un matériau indisponible, un aléa de terrain, une contrainte découverte en creusant. Ces arbitrages sont consignés au fil de l'eau, avec leur motif.

Le document d'architecture souffre du même décalage. Il décrit un état à un instant donné, et il vieillit à partir du lendemain. Les décisions prises après sa rédaction n'ont nulle part où aller, et six mois plus tard plus personne ne sait pourquoi le cache a été retiré.

Les Architecture Decision Records répondent exactement à ce problème. Le format a été proposé par Michael Nygard dans un billet de novembre 2011, et il est resté volontairement minimal : un titre, un statut, le contexte, la décision, les conséquences.

Un ADR est un fichier court, versionné à côté du code, numéroté, jamais modifié une fois accepté. Quand une décision change, on n'édite pas l'ancien enregistrement : on en écrit un nouveau qui remplace le précédent, et l'ancien passe au statut « remplacé ».

## ADR-014 : réception des mesures en HTTP plutôt qu'en MQTT

### Statut
Accepté, remplace l'ADR-009

### Contexte
Les capteurs de première génération savent poster en HTTP.
L'équipe d'exploitation n'a aucune expérience d'un courtier MQTT.

### Décision
La passerelle expose une seule route HTTP en écriture par lot.
MQTT est reporté à la génération suivante de capteurs.

### Conséquences
Plus de connexions à absorber côté passerelle, à compenser par le
répartiteur de charge. Le futur portage MQTT devra réutiliser le
même validateur, qui reste donc indépendant du transport.

La pratique est référencée sous le nom de Lightweight Architecture Decision Records au Technology Radar de ThoughtWorks, classée en « Adopt ». Une communauté maintient des gabarits et des outils sur adr.github.io.

L'intérêt réel se mesure au moment d'une reprise de projet. Le document dit ce que le système est, les ADR disent pourquoi il est comme ça, et la seconde information est celle qui manque toujours.

Le document d'architecture est une photo, les ADR sont le film. Sans le film, chaque nouvelle équipe rediscute des décisions déjà tranchées, sans savoir qu'elles l'ont été.

Étude de cas : une plateforme de supervision d'objets connectés

Assez de méthode. Voici un système à concevoir, avec les mêmes contraintes qu'en vrai : un client qui sait ce qu'il veut fonctionnellement, et qui n'a jamais pensé au reste.

La demande initiale tient en une phrase. « On veut superviser nos capteurs industriels depuis un tableau de bord, et être alerté quand une mesure sort des clous. »

Les questions posées, et les chiffres obtenus

Cette phrase ne permet de construire strictement rien. Voici les questions posées en réunion de cadrage, et les réponses obtenues après insistance.

Deux réponses de cette table valent tout le reste. Le délai de 30 secondes entre la mesure et l'alerte autorise un traitement asynchrone, donc une file de messages. Et la dissociation des deux SLA permet de dimensionner différemment les deux moitiés du système, ce qui change le budget.

Le calcul, fait explicitement

Les chiffres du client ne sont pas des exigences techniques. Ils le deviennent après une multiplication qu'il faut poser noir sur blanc dans le document.

Débit moyen        : 50 000 capteurs / 60 s          = 833 messages/s
Débit de pointe    : facteur 3 retenu                = 2 500 messages/s
Mesures par jour   : 50 000 x 1 440                  = 72 000 000
Volume brut / jour : 72 000 000 x 200 octets         = 14,4 Go
Volume brut / an   : 14,4 Go x 365                   = 5,3 To
Année 2 (65 000 capteurs)                            = 6,8 To
Année 3 (84 500 capteurs)                            = 8,9 To
Cumul à 3 ans, hors index et compression             = 21 To

Le facteur de pointe est une hypothèse, pas une mesure. Il figure dans le document comme telle, avec sa justification : les capteurs se synchronisent naturellement après une coupure d'alimentation et réémettent en rafale.

Un chiffre d'exigence non-fonctionnelle qui n'est pas posé au tableau reste une intuition. Poser le calcul, c'est aussi rendre l'hypothèse discutable par quelqu'un d'autre.

La cartographie des composants

Quatre responsabilités se dégagent : recevoir, traiter, consulter, tracer. Elles deviennent quatre composants, plus les magasins et le tampon qui les relient.

Lecture commentée. Un capteur poste un lot de mesures sur la passerelle, qui valide le format et l'existence du capteur, publie dans la file et répond immédiatement. Le moteur de règles consomme la file, écrit les mesures dans le magasin de séries temporelles, évalue les seuils définis dans le référentiel et déclenche une alerte si nécessaire. L'application web n'interroge jamais les magasins directement : elle passe par l'API de consultation. Les trois composants exécutables envoient leurs traces au même service de journalisation.

Deux magasins distincts, et c'est délibéré. Les mesures sont un flux append-only, énorme et jamais modifié. Le référentiel des capteurs, des sites, des utilisateurs et des règles est petit, très structuré, et réclame des transactions. Un seul magasin pour les deux servirait mal les deux.

Les modes de communication

Chaque flèche du schéma est une décision, jugée sur les critères posés dans le billet consacré à la messagerie inter-services.

Le choix de la file est le plus structurant du système. Sans elle, un pic de réémission après coupure se propage directement jusqu'au magasin de données. Avec elle, la passerelle continue d'accepter et le moteur rattrape son retard.

Type d'application et stack par composant

Le type d'application se choisit avant la technologie, et il découle du profil d'usage de chaque composant.

La justification la plus faible de ce tableau est aussi la plus honnête : une seule stack serveur pour trois composants, parce que l'exploitation du client compte deux personnes. Une contrainte extérieure a tranché à la place d'un critère technique, et le document le dit.

L'architecture interne de deux composants

Le document détaille chaque composant. Voici les deux qui portent l'essentiel du risque.

La passerelle n'a aucune couche d'accès aux données, et c'est sa propriété la plus importante. Elle ne parle qu'à la file, ce qui la rend triviale à répliquer et à redémarrer.

Le format d'une mesure reste volontairement pauvre, parce que chaque octet est multiplié par 72 millions chaque jour.

{
  "sensorId": "cap-00317",
  "ts": "2026-03-12T08:41:07Z",
  "values": { "temp": 61.4, "pressure": 3.2, "vibration": 0.08 }
}

Le moteur de règles, lui, porte toute la logique métier et tous les accès en écriture. C'est le composant qu'on teste le plus, et le seul dont une exception non traitée fait perdre des mesures.

La conformité aux exigences non-fonctionnelles

Dernier tableau du document, et le plus regardé en revue. Il met face à face chaque chiffre arraché au client et la décision qui y répond.

Ce tableau est le point où le document cesse d'être une intention. Chaque ligne est opposable en recette, et chaque décision technique du reste du document se rattache à l'une d'elles.

Reste ce que le document ne fige pas. Le passage éventuel des capteurs à MQTT, l'archivage froid au-delà de treize mois, le découpage du moteur de règles en plusieurs services si la charge dépasse les hypothèses : trois sujets ouverts, qui iront dans des ADR le jour où ils se trancheront.

L'étude de cas ne prouve pas qu'on a trouvé la bonne architecture. Elle prouve qu'on peut expliquer chacune de ses décisions par un chiffre obtenu auprès du client.

Points clés

• Le document d'architecture précède le code, jamais l'inverse. Écrit après, il devient un compte rendu que personne ne lit et qui n'engage personne.
• Cinq sections, cinq lectorats. Résumé exécutif pour la direction, contexte pour le vocabulaire, exigences pour l'engagement, vue d'ensemble pour la carte, détail par composant pour ceux qui construisent.
• Une exigence non-fonctionnelle sans chiffre n'existe pas. Le calcul de volumétrie et de charge se pose explicitement dans le document, hypothèses comprises, pour qu'on puisse le contester.
• Le format se choisit sur le lecteur, pas sur la rigueur. Boîtes, flèches, légende et tableaux circulent mieux qu'une notation formelle que la moitié de l'équipe déchiffre approximativement.
• Les ADR complètent ce que le document fige. Ils gardent le pourquoi des décisions prises après la rédaction, et évitent de rediscuter indéfiniment des arbitrages déjà tranchés.

Dans la série

Palier 3 : Conduire le chantier. Domaine : Information.

• Précédent : Microservices, Event Sourcing et CQRS : quand et pourquoi
• Vue d'ensemble : Architecture logicielle : par où commencer

Ce billet clôt la série. Le chantier est livré, le dossier est remis, et le suivant commence par une étude de sol.

Pour aller plus loin

• Le processus d'architecture : six étapes, des exigences au support, pour revenir au palier 1 et à la façon d'obtenir les chiffres utilisés dans l'étude de cas
• Le métier d'architecte : rôle, mindset et influence sans autorité, parce qu'un document ne s'impose pas tout seul en réunion
• Documenting Architecture Decisions, le billet de Michael Nygard qui a fixé le format des ADR
• Lightweight Architecture Decision Records au Technology Radar de ThoughtWorks, et les gabarits communautaires sur adr.github.io
• Le modèle C4 pour les niveaux de zoom, et arc42 pour une trame de document complète
• La spécification UML de l'OMG, si ton lectorat la maîtrise vraiment