Diagrammes en tant que code et documentation à jour

Ce que signifient les diagrammes en tant que code

Les diagrammes en tant que code (diagrams as code) consistent à écrire un diagramme sous forme d’un court fichier texte, dans un petit langage, et à laisser un outil le mettre en page et le dessiner. Au lieu de faire glisser des boîtes sur un canevas, vous écrivez ordering -> db: SQL, et l’outil produit l’image. Le fichier texte vit dans le dépôt de code et il est traité comme du code : versionné, relu, vérifié par des builds automatisés et publié par le pipeline.

C’est une composante de la documentation en tant que code (docs as code), pratique défendue par la communauté Write the Docs, qui consiste à produire la documentation avec les mêmes outils et le même flux de travail que le logiciel : outils de suivi des tickets, gestion de versions (généralement Git), balisage en texte brut comme Markdown ou AsciiDoc, revue de code et tests automatisés. Les sections précédentes ont produit la matière : vues et diagrammes C4, UML là où la précision compte, ADR et structure arc42. Cette section porte sur la manière de garder cette matière exacte pendant toute la vie du système, et c’est là que la plupart des documentations d’architecture échouent. Les raisons de cet échec ont été exposées dans pourquoi documenter, et dans quelle mesure : des wikis périmés, de gros documents dont personne n’est responsable et des diagrammes qui ne correspondent plus au système.

Pourquoi mettre les diagrammes en texte

Gestion de versions. Un diagramme en texte a un historique. Vous pouvez voir qui l’a modifié, quand et pourquoi, et comparer deux versions quelconques ligne par ligne ; une image binaire ou un fichier au format d’un outil de dessin montre seulement que quelque chose a changé. Vous pouvez aussi créer une branche : le diagramme d’une modification proposée vit sur la même branche que le code qui la met en œuvre.

Relecture dans les pull requests. Quand un développeur ajoute une nouvelle dépendance entre des services, la modification du diagramme apparaît dans la même pull request que le code, sous forme de diff textuel lisible. Les relecteurs peuvent demander si la nouvelle flèche est voulue : c’est une revue d’architecture au moment où elle coûte le moins cher.

Cohérence. L’outil applique les mêmes formes, polices et règles de mise en page à chaque diagramme, si bien que des diagrammes dessinés par vingt personnes ressemblent toujours à un ensemble unique. Avec un langage de modélisation (voir plus bas), le même élément apparaît avec le même nom et la même description dans chaque vue.

Génération. Du texte peut être produit par des programmes. Les diagrammes peuvent être générés à partir du code lui-même (graphes de dépendances), de l’infrastructure en tant que code (diagrammes de déploiement), des spécifications d’API ou d’un modèle central, puis vérifiés automatiquement par rapport au système.

Les compromis sont réels. La mise en page automatique est pratique mais parfois laide, et lutter contre un moteur de mise en page pour placer une seule boîte peut prendre plus de temps que de la dessiner ; la plupart des outils proposent des indications, comme la direction ou le regroupement, pas des positions exactes. Les langages textuels demandent un apprentissage aux personnes qui ne codent pas, comme les product managers. Et un beau croquis au tableau blanc pendant une discussion de conception reste la manière la plus rapide de réfléchir ; les diagrammes en tant que code sont destinés aux diagrammes que vous comptez conserver.

Quatre langages, un exemple

Quatre langages dominent. Chaque exemple ci-dessous décrit une partie de la même plateforme de livraison de repas.

PlantUML, créé par Arnaud Roques et publié pour la première fois en 2009, est le plus ancien des quatre. Il couvre tous les diagrammes UML courants (séquence, composants, déploiement, états, activités, classes) et bien d’autres, et utilise Graphviz pour mettre en page la plupart des types de diagrammes. La bibliothèque C4-PlantUML ajoute les formes C4. Ses diagrammes de séquence sont particulièrement réussis, ce qui en fait un choix naturel pour les scénarios d’exécution de l’essentiel d’UML.

@startuml
title Place an order (happy path)
actor Customer
participant "Customer app" as App
participant "Ordering service" as Ord
participant "Payment provider" as Pay
queue "Order events topic" as MB

Customer -> App : Tap "Pay"
App -> Ord : POST /orders (HTTPS)
Ord -> Pay : Authorise payment
Pay --> Ord : Authorised
Ord ->> MB : OrderPlaced (async)
Ord --> App : 201 Created
@enduml

Mermaid, créé par Knut Sveidqvist en 2014, est écrit en JavaScript et s’affiche dans le navigateur. Son principal atout est sa portée : GitHub affiche les blocs Mermaid dans les fichiers Markdown depuis février 2022, et GitLab ainsi que de nombreux wikis et outils de prise de notes font de même, si bien qu’un diagramme dans un README ne demande aucune étape de build. Il prend en charge, entre autres, les organigrammes et les diagrammes de séquence, de classes, d’états et entité-association, et propose une prise en charge expérimentale de C4. Sa maîtrise de la mise en page est limitée pour les grands diagrammes.

flowchart LR
    app["Customer app<br/>Kotlin, Swift"]
    gw["API gateway"]
    ord["Ordering service<br/>Java"]
    db[("Order database<br/>PostgreSQL")]
    topic[["Order events<br/>Kafka topic"]]
    disp["Dispatch service<br/>Go"]
    notif["Notification service<br/>Node.js"]

    app -->|HTTPS/JSON| gw
    gw -->|HTTPS/JSON| ord
    ord -->|SQL| db
    ord -->|publishes OrderPlaced| topic
    disp -->|consumes| topic
    notif -->|consumes| topic

Structurizr DSL, créé par Simon Brown en parallèle du modèle C4, est d’une autre nature. Il ne décrit pas un diagramme ; il décrit un modèle (personnes, systèmes logiciels, conteneurs, composants et relations entre eux), puis définit des vues de ce modèle. Chaque élément est défini une seule fois, avec son nom, sa description et sa technologie, et apparaît dans chaque vue qui l’inclut. Les relations entre conteneurs sont automatiquement déduites au niveau du système, si bien que la vue de contexte n’a pas besoin de flèches séparées. Le DSL peut aussi rattacher au workspace une documentation Markdown et un dossier d’ADR, et l’outillage peut exporter les vues vers PlantUML, Mermaid, D2 et d’autres formats.

workspace "Food delivery" {
    model {
        customer = person "Customer" "Orders food from local restaurants."
        payments = softwareSystem "Payment provider" "Takes card payments." "External"
        platform = softwareSystem "Food-delivery platform" {
            app = container "Customer app" "Ordering and tracking." "Kotlin, Swift"
            gateway = container "API gateway" "Authenticates and routes requests." "Managed API gateway"
            ordering = container "Ordering service" "Accepts and tracks orders." "Java"
            db = container "Order database" "Orders and their states." "PostgreSQL" "Database"
            orderEvents = container "Order events" "Order lifecycle events." "Kafka topic" "Topic"
            dispatch = container "Dispatch service" "Assigns couriers." "Go"
        }
        customer -> app "Places and tracks orders using"
        app -> gateway "Makes API calls to" "JSON/HTTPS"
        gateway -> ordering "Routes requests to" "JSON/HTTPS"
        ordering -> db "Reads from and writes to" "SQL/TCP"
        ordering -> payments "Takes card payments using" "JSON/HTTPS"
        ordering -> orderEvents "Publishes order events to" "Kafka"
        dispatch -> orderEvents "Consumes order events from" "Kafka"
    }
    views {
        systemContext platform "Context" {
            include *
            autoLayout lr
        }
        container platform "Containers" {
            include *
            autoLayout lr
        }
        styles {
            element "Database" {
                shape cylinder
            }
            element "Topic" {
                shape pipe
            }
        }
    }
}

D2 (Declarative Diagramming), publié en open source par Terrastruct en 2022, est le plus récent. Il vise un rendu net et moderne et une syntaxe lisible, prend en charge les conteneurs imbriqués (écrits avec des accolades et désignés par des noms à points), et offre le choix entre plusieurs moteurs de mise en page : dagre et ELK sont fournis et gratuits, et TALA, conçu pour les diagrammes d’architecture logicielle, est un moteur commercial distinct.

direction: right

customer: Customer {shape: person}
payments: Payment provider

platform: Food-delivery platform {
  app: Customer app
  ordering: Ordering service
  db: Order database {shape: cylinder}
  events: Order events topic {shape: queue}
  dispatch: Dispatch service

  app -> ordering: Places order (HTTPS)
  ordering -> db: SQL
  ordering -> events: Publishes OrderPlaced
  dispatch -> events: Consumes OrderPlaced
}

customer -> platform.app: Places orders using
platform.ordering -> payments: Authorise (HTTPS)

Outils de dessin et outils de modélisation

La différence entre Structurizr et les trois autres illustre la distinction entre outils de dessin et outils de modélisation présentée à la section 4.3. Un outil de dessin (diagrams.net, Excalidraw, Visio, un tableau blanc en ligne, mais aussi PlantUML, Mermaid et D2) connaît des formes, des lignes et du texte. Une boîte libellée Service Commandes dans un diagramme n’a aucun lien avec la boîte portant le même libellé dans un autre. Renommez le service, et vous devez retrouver et corriger chaque diagramme à la main ; faites une seule faute de frappe, et vous avez, pour l’outil, deux services.

Un outil de modélisation (Structurizr, Archi pour les modèles ArchiMate, Sparx Enterprise Architect pour UML et SysML, Capella) conserve un modèle : un référentiel d’éléments et de relations dotés de propriétés. Les diagrammes sont des vues sur ce modèle. Renommez un élément, et toutes les vues changent. Le modèle peut être interrogé (quels conteneurs dépendent du broker ?), vérifié (aucun composant de l’app client ne doit appeler la base de données) et comparé au système en fonctionnement. Le prix à payer est davantage de structure en amont et, avec les outils commerciaux lourds, des licences, de la formation et une tendance à modéliser bien plus que ce que quiconque lit.

Une règle pratique : utilisez des outils de dessin, textuels ou graphiques, pour les croquis, les explications ponctuelles et les diagrammes autonomes, comme un diagramme de séquence isolé dans un ADR. Utilisez un modèle quand les mêmes éléments apparaissent dans de nombreux diagrammes, quand plusieurs équipes contribuent, ou quand vous voulez vérifier la documentation par rapport au code. Beaucoup d’équipes combinent les deux : un modèle Structurizr pour la structure C4, et PlantUML ou Mermaid pour quelques diagrammes de séquence et d’états.

Générer la documentation dans le pipeline

Dès que la documentation est du texte dans le dépôt, le pipeline d’intégration continue vu au chapitre 0 peut la construire et la vérifier comme du code. Un pipeline type rend chaque diagramme (en faisant échouer le build en cas d’erreur de syntaxe), vérifie les liens, construit un site de documentation statique avec un générateur comme MkDocs, Antora ou Docusaurus, et le publie quand les modifications arrivent sur la branche principale. Les lecteurs voient alors toujours la documentation qui correspond au code de main, et personne n’a besoin de penser à exporter une image pour l’envoyer sur un wiki.

D’autres vérifications peuvent s’ajouter à mesure que l’équipe gagne en maturité : un correcteur orthographique et un linter de rédaction (Vale est populaire), une vérification que chaque ADR a un statut valide, un avertissement quand la date de dernière revue d’une page dépasse son intervalle de revue, et des vérifications d’architecture qui comparent les dépendances documentées avec les dépendances réelles du code, ce qui est une forme de fonction d’aptitude. Certaines équipes génèrent une partie de la documentation à partir du système lui-même : graphes de dépendances issus du build, référence d’API issue des spécifications OpenAPI, diagrammes de déploiement issus de l’infrastructure en tant que code.

name: architecture-docs
on:
  pull_request:
    paths: ["docs/**"]
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # assumes plantuml, d2, lychee and mkdocs are available on the runner
      - name: Render diagrams (fails on syntax errors)
        run: |
          plantuml -tsvg docs/diagrams/*.puml
          for f in docs/diagrams/*.d2; do d2 "$f" "${f%.d2}.svg"; done
      - name: Check links
        run: lychee --offline docs/
      - name: Build site (warnings such as broken links fail the build)
        run: mkdocs build --strict
      - name: Publish
        if: github.ref == 'refs/heads/main'
        run: ./scripts/publish-docs.sh

Garder la documentation à jour

Ce ne sont pas les outils qui gardent la documentation exacte, ce sont les habitudes. Cinq habitudes font la différence.

Responsabilité. Chaque document a un responsable nommé, normalement l’équipe responsable du code qu’il décrit. Dans GitHub et GitLab, un fichier CODEOWNERS peut faire de cette équipe un relecteur obligatoire pour les modifications de son dossier docs/. Les documents qui appartiennent à tout le monde ne sont maintenus par personne.

Relecture avec les modifications du code. Un modèle de pull request qui demande Cette modification touche-t-elle une interface, une dépendance, un déploiement ou une décision ? Si oui, quel document ou quel ADR avez-vous mis à jour ? attrape la plupart des dérives au moment où elles se produisent. Certaines équipes vont plus loin et bloquent la fusion des fonctionnalités dépourvues de documentation, une pratique que mentionne le guide de Write the Docs.

Dates de dernière revue. Un petit en-tête sur chaque page indique son responsable, la date de sa dernière vérification par rapport à la réalité et la fréquence à laquelle elle doit être revue. Les lecteurs peuvent juger dans quelle mesure s’y fier, et le pipeline peut signaler les pages en retard. Une page qui indique dernière revue : 2023 est honnête ; une page qui décrit en silence le système de 2023 est un piège.

Relier documentation et code. Les pages pointent vers le code qu’elles décrivent (chemins, modules), les commentaires du code pointent vers les ADR, et les messages de commit citent les enregistrements qu’ils mettent en œuvre. Des liens dans les deux sens rendent évident quels documents une modification peut affecter.

Supprimer ce qui est périmé. Une documentation fausse est pire que pas de documentation du tout, car les lecteurs agissent en fonction d’elle. Quand une page ne décrit plus le système et que personne ne la corrigera, supprimez-la ou déplacez-la dans une archive clairement signalée. Les ADR font exception : ce sont des traces de l’histoire, ils sont donc remplacés ou dépréciés, pas supprimés. C’est l’idée de documentation vivante que Cyrille Martraire a développée dans son livre de 2019 portant ce titre : une documentation qui évolue au même rythme que le système, idéalement parce qu’une grande partie en est dérivée du système lui-même.

---
title: "Ordering service: building block view (level 2)"
owner: "@ordering-team"
last_reviewed: 2026-09-14
review_every: 6 months
code: src/ordering/
decisions: [ADR-0007, ADR-0012]
---