Mise en œuvre

Du fichier workspace.dsl à des diagrammes consultables, versionnés et vérifiés en intégration continue.

Le serveur local

C’est la façon la plus rapide de voir ses diagrammes : un conteneur Docker qui lit un workspace.dsl dans un dossier et sert une interface web.

docker run -it --rm -p 8080:8080 \
  -v "$PWD:/usr/local/structurizr" \
  structurizr/structurizr local
Warning

La commande était auparavant l’image structurizr/lite, sans argument — forme que l’on trouve encore partout en ligne. Elle est dépréciée et n’affiche plus qu’une bannière de migration. Le point de montage et le port sont restés identiques, la migration se réduit donc à changer le nom de l’image et à ajouter local.

Le navigateur sur http://localhost:8080 affiche les vues, et recharge le modèle à chaque rafraîchissement de page — la boucle de travail consiste donc à éditer le DSL dans son éditeur et à rafraîchir. Aucun compte, aucune configuration.

Lite reconnaît par convention les dossiers voisins du workspace :

architecture/
  workspace.dsl        le modèle et les vues
  docs/                documentation Markdown ou AsciiDoc
  adrs/                Architecture Decision Records
  workspace.json       généré par Lite — positions manuelles, à versionner ou non
Tip

Un alias dans les dotfiles évite de retaper la commande :

alias structurizr='docker run -it --rm -p 8080:8080 -v "$PWD:/usr/local/structurizr" structurizr/structurizr local'

Lite permet aussi de déplacer les éléments à la souris et enregistre les positions dans workspace.json. C’est le recours quand autolayout ne donne rien de bon — au prix d’un fichier généré à gérer, dont il faut décider s’il entre dans le dépôt. Le versionner rend les positions reproductibles ; ne pas le versionner évite un fichier bruyant en revue. Le premier choix est préférable dès qu’un diagramme a été placé à la main.

Exporter et valider

La même image, avec une autre commande.

docker run --rm -v "$PWD:/usr/local/structurizr" structurizr/structurizr \
  export -workspace workspace.dsl -format mermaid -output out
FormatUsage
mermaidIntégration dans un site statique — Hugo, MkDocs, GitHub
plantuml/c4plantumlPlantUML avec la bibliothèque C4, rendu proche des conventions officielles
plantuml/structurizrPlantUML au rendu Structurizr
dotGraphviz, pour un post-traitement
ilographImport dans Ilograph
jsonLe workspace sérialisé — utile en entrée d’autres outils
dslReconvertit un JSON en DSL
websequencediagramsDiagrammes de séquence, pour les vues dynamiques
d2Import dans D2

La validation ne produit aucun fichier mais sort en code non nul sur un DSL invalide, ce qui en fait la commande à mettre en CI :

docker run --rm -v "$PWD:/usr/local/structurizr" structurizr/structurizr \
  validate -workspace workspace.dsl

Les messages d’erreur sont précis et donnent la ligne — The destination element "inexistant" does not exist at line 4 — ce qui rend la commande utilisable comme retour immédiat pendant l’écriture, et pas seulement en CI.

inspect va plus loin en appliquant des contrôles de qualité au modèle : éléments sans description, relations sans technologie, vues vides. C’est le complément naturel de validate, qui ne vérifie que la syntaxe et les références.

Les autres commandes — push, pull, lock, unlock, list, branches — ne concernent qu’un serveur distant.

Note

L’export vers Mermaid a une limite à connaître : les diagrammes de déploiement et les vues dynamiques y perdent une partie de leur mise en forme, Mermaid n’ayant pas d’équivalent exact. Pour une documentation où le rendu compte, plantuml/c4plantuml est plus fidèle ; pour une intégration sans chaîne de rendu supplémentaire — le cas de ce site, dont le thème gère Mermaid nativement — Mermaid reste le plus pratique.

Documentation et décisions

Deux directives transforment Structurizr en outil de documentation, et non seulement de diagrammes.

workspace "Billetterie" {

    model {
        // ...
    }

    views {
        // ...
    }

    !docs docs
    !adrs adrs
}

!docs rattache un dossier de fichiers Markdown ou AsciiDoc, numérotés pour fixer l’ordre. Ils peuvent incorporer les vues du modèle, ce qui donne une documentation dont les schémas ne peuvent pas être périmés :

## Les conteneurs

L'API porte les règles de placement et de tarification.

![](embed:Conteneurs)

embed: prend la clé de la vue — d’où l’intérêt de clés stables et explicites.

!adrs rattache un dossier d’ADR, que Structurizr affiche avec leur statut et leur graphe de remplacement. C’est le complément direct du modèle : les vues montrent la structure, les ADR disent pourquoi elle est ainsi.

adrs/
  0001-choix-de-postgresql.md
  0002-separation-billetterie-fidelite.md
  0003-abandon-du-bus-maison.md

En intégration continue

Trois choses valent d’être automatisées, par ordre de valeur.

Valider le DSL sur chaque proposition de modification. Un workspace.dsl invalide casse la documentation pour tout le monde ; la validation coûte quelques secondes.

Exporter les diagrammes et les publier. Soit en artefacts, soit dans un site statique.

Pousser vers la version hébergée, le cas échéant.

name: Architecture
on:
  pull_request:
    paths: ['architecture/**']
  push:
    branches: [master]

jobs:
  workspace:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Valider le workspace
        run: |
          docker run --rm -v "$PWD/architecture:/usr/local/structurizr" \
            structurizr/structurizr validate -workspace workspace.dsl

      - name: Exporter les diagrammes
        run: |
          docker run --rm -v "$PWD/architecture:/usr/local/structurizr" \
            structurizr/structurizr export -workspace workspace.dsl \
            -format mermaid -output diagrammes

      - uses: actions/upload-artifact@v4
        with:
          name: diagrammes
          path: architecture/diagrammes
Tip

Le vrai bénéfice n’est pas l’automatisation, c’est la revue. Un git diff sur le DSL montre l’évolution de l’architecture en quelques lignes lisibles — un conteneur ajouté, une relation supprimée. Une modification d’architecture devient alors une proposition de modification comme une autre, discutable avant d’être appliquée. C’est ce qu’aucun outil graphique ne permet, et c’est ce qui justifie à lui seul le passage au DSL.

Les pièges

Sur-modéliser. La tentation de tout décrire est forte, et le modèle devient alors un inventaire que personne ne lit ni ne maintient. Le critère est l’usage : un élément qui n’apparaît dans aucune vue utile n’a pas à figurer dans le modèle.

Confondre le modèle et la réalité. Rien ne relie le DSL au code déployé. La seule discipline qui fonctionne est de traiter le workspace comme du code : dans le même dépôt, dans la même proposition de modification que le changement qu’il décrit.

Se battre avec autolayout. Y passer une heure signale presque toujours une vue trop chargée. Filtrer avant de régler.

Des clés de vue instables. Elles servent aux noms de fichiers exportés et aux embed: de la documentation. Les fixer explicitement, dès le début.

Le niveau 3 partout. Un diagramme de composants par conteneur, c’est la garantie d’un modèle périmé en trois mois. Le réserver aux conteneurs qui le méritent.

Dépendre d’un thème distant. Un theme default suffit à rendre l’export tributaire d’un service tiers — et celui-ci ferme le 30 septembre 2026. Rapatrier les thèmes, ou écrire ses styles à la main.

Suivre un tutoriel de 2024. Les images structurizr/lite et structurizr/cli sont dépréciées et silencieusement inertes : la CLI ne valide plus rien tout en sortant en code 0, ce qui donne une CI verte qui ne vérifie rien. Vérifier que l’on utilise bien structurizr/structurizr.

Attendre le modèle parfait avant de partager. Un diagramme de contexte et un diagramme de conteneurs, imparfaits mais à jour, valent infiniment mieux qu’un modèle complet jamais publié.

Les alternatives

OutilPositionnement
C4-PlantUMLUne bibliothèque PlantUML de macros C4. Plus simple à intégrer, mais pas de modèle : chaque diagramme est indépendant, avec la dérive que cela implique
LikeC4Alternative moderne, un modèle unique également, sortie web interactive soignée. Écosystème plus jeune
Mermaid C4Support C4 expérimental de Mermaid. Pratique parce que rendu partout — GitHub, ce site — mais limité et sans modèle
IcePanelSaaS graphique, orienté équipes non techniques. À l’opposé de l’approche as-code
Diagrammes à la mainExcalidraw, draw.io. Parfaits pour un schéma jetable en réunion ; à ne pas confondre avec de la documentation

Le choix se résume à une question : voulez-vous un modèle ou des images ? Si plusieurs diagrammes doivent rester cohérents entre eux dans le temps, il faut un modèle, et Structurizr est l’implémentation de référence pour C4. Pour un schéma unique dans un fichier README, Mermaid directement est plus raisonnable.

Références