Structurizr
Structurizr est l’outillage du modèle C4, écrit par son auteur, Simon Brown. Son idée directrice tient en une phrase, et c’est elle qui le distingue de tous les outils de dessin :
Un modèle, plusieurs vues.
On ne dessine pas des diagrammes : on décrit une fois les éléments et leurs relations, puis on déclare les vues à en extraire. Le niveau 1, le niveau 2 et le diagramme de déploiement deviennent trois projections du même modèle, qu’il devient structurellement impossible de faire diverger.
Le workspace
L’unité de travail est le workspace, qui contient trois choses :
| Bloc | Contenu |
|---|---|
model | Les éléments — personnes, systèmes, conteneurs, composants, nœuds de déploiement — et leurs relations |
views | Les vues à produire, et les styles qui les habillent |
configuration | La portée, la visibilité, les droits — utile surtout pour la version hébergée |
Un workspace se décrit soit dans le DSL — un fichier texte, versionné avec le code —, soit par programme via les bibliothèques Java, .NET, TypeScript ou Python. Dans les deux cas, la représentation canonique est un JSON que les outils consomment.
Tip
Le DSL est le bon choix par défaut, et de très loin. Les bibliothèques ne se
justifient que pour générer un modèle à partir d’une source existante — scanner
un code base pour en déduire les composants, lire un inventaire, interroger une
API de cloud. Pour tout le reste, un fichier workspace.dsl de deux cents lignes
à côté du code est plus simple à écrire, à relire et à diffuser.
L’écosystème
Warning
L’outillage a été consolidé en 2026. Les images structurizr/lite et
structurizr/cli, encore massivement citées dans les articles en ligne, sont
dépréciées : elles n’affichent plus qu’une bannière invitant à migrer, et la CLI ne
valide même plus. Tout passe désormais par une image unique,
structurizr/structurizr, dont la commande choisit le mode.
Par ailleurs, le service hébergé Structurizr Cloud atteint sa fin de vie le
30 septembre 2026, ce qui emporte les thèmes servis depuis
static.structurizr.com — voir
Vues et styles.
Une image, plusieurs commandes :
| Commande | Rôle |
|---|---|
local | Serveur local, un seul workspace : vues, documentation et ADR. Remplace Structurizr Lite |
server | Serveur multi-workspaces, pour un hébergement partagé |
validate | Vérifie le DSL — la commande à mettre en intégration continue |
export | Exporte vers Mermaid, PlantUML, D2, DOT, Ilograph, JSON |
inspect | Applique des contrôles de qualité au modèle |
push, pull, lock, unlock, list | Échanges avec un serveur distant |
playground | Bac à sable éphémère, sans fichier |
À quoi s’ajoutent, hors image Docker, le DSL lui-même et les bibliothèques Java, .NET, TypeScript et Python pour construire un modèle par programme.
Ce qu’il faut choisir
DSL + local, dans le dépôt du projet. C’est la combinaison qui couvre
l’immense majorité des besoins : le fichier vit avec le code, il passe en revue avec
le reste, et une commande Docker le rend consultable. Aucun compte, aucun
abonnement, aucun serveur à administrer.
Ajouter validate et export dès qu’il faut vérifier en CI, ou publier
ailleurs : Mermaid ou PlantUML pour intégrer les diagrammes dans un site statique,
comme celui-ci.
server seulement si le partage devient un besoin réel : plusieurs équipes, des
lecteurs non techniques, un historique à conserver. Ce n’est pas un prérequis,
contrairement à ce que laisse parfois entendre la documentation commerciale — et
c’est désormais la seule voie hébergée, la version cloud fermant.
Ce que Structurizr apporte réellement
Au-delà du confort, trois bénéfices qui changent la nature de l’exercice.
La cohérence est garantie, pas surveillée. Un élément renommé l’est dans toutes les vues. Une relation absente du modèle ne peut apparaître dans aucun diagramme. Ce n’est pas de la rigueur : c’est une propriété de l’outil.
Les diagrammes deviennent relisables. Un git diff sur un workspace.dsl
montre exactement ce qui a changé dans l’architecture — trois lignes ajoutées, un
conteneur supprimé. Aucun outil graphique ne permet cela, et c’est ce qui rend
possible la revue d’une évolution d’architecture au même titre qu’une revue de code.
La documentation cesse de dériver. Le fichier étant dans le dépôt, il fait partie du travail, et une modification d’architecture qui ne le met pas à jour se voit en revue.
Warning
Ce que Structurizr ne fait pas : garantir que le modèle décrit la réalité. Rien
ne relie le workspace.dsl au code réellement déployé. La dérive reste possible —
elle est simplement devenue visible et réparable en un seul endroit, au lieu d’être
répartie dans huit images PNG.
La suite
- Structure d’un workspace, éléments du modèle, relations, déploiement, identifiants hiérarchiques, inclusions et modularité.
- Les sept types de vues, les expressions d’inclusion, la mise en page automatique, les styles par étiquette et les thèmes.
- Lite en Docker, export CLI, documentation et ADR, validation en CI, et les pièges à connaître.
Références
- https://structurizr.com/
- https://docs.structurizr.com/ — la documentation de référence
- https://github.com/structurizr — DSL, CLI et Lite, tous libres