Comment faire un diagramme d'architecture logicielle : guide étape par étape

Quand vous dessinez votre premier diagramme d'architecture, le plus difficile n'est pas de tracer des boîtes, mais de décider ce que vous laissez de côté. Ce guide porte sur les diagrammes d'architecture logicielle et système : services, bases de données, files de messages, zones réseau et connexions entre eux. Qu'il s'agisse de votre premier diagramme d'architecture logicielle ou du dixième de votre équipe, les étapes ci-dessous vous aident à produire un schéma lisible et qui reste à jour.

Commencez par le lecteur et la question

Un bon diagramme répond à une seule question. « Tout notre système » n'est pas une question : c'est un inventaire, et un inventaire a sa place dans un tableau.

Avant de tracer quoi que ce soit, écrivez deux phrases :

• Qui va le lire ? Une développeuse qui vient d'arriver, le SRE d'astreinte, une revue de sécurité, un product manager, un auditeur externe.
• À quelle question répond-il ? « Par quels services passe une requête de commande ? », « Qu'est-ce qui est exposé à Internet ? », « Où part le trafic si une région tombe ? »

Ces deux phrases fixent le périmètre. Une nouvelle recrue n'a pas besoin du même niveau de détail que l'équipe réseau. Vouloir servir les deux avec une seule image, c'est n'en servir aucun.

Choisissez le type de diagramme

Une fois la question claire, le type s'impose presque de lui-même. Le modèle C4 est un bon point de départ : il découpe un système en niveaux de zoom appelés context, container, component et code (détails sur c4model.com).

En cas de doute, commencez par un diagramme de contexte. Il rend explicites la frontière du système et ses dépendances externes, et sert de cadre à tous les diagrammes suivants.

Faire un diagramme d'architecture, étape par étape

1. Définissez le périmètre et la frontière

Écrivez ce qui est dans le diagramme et ce qui reste dehors. Les composants dont votre équipe est propriétaire sont à l'intérieur de la frontière ; un prestataire de paiement, un fournisseur d'identité ou le service d'une autre équipe restent à l'extérieur. Représentez chaque système externe par une seule boîte : son fonctionnement interne ne vous concerne pas.

2. Listez les composants

Faites une liste avant de dessiner : services, bases de données, files, caches, API externes, types d'utilisateurs. Utilisez les noms que l'équipe emploie vraiment ; s'ils correspondent au nom du dépôt ou du déploiement, c'est encore mieux. Si la liste est trop longue pour être saisie d'un coup d'œil, vous avez probablement de quoi faire deux diagrammes.

3. Tracez les relations avec des flèches orientées et annotées

Un trait sans libellé dit seulement que deux éléments sont « liés d'une manière ou d'une autre ». Donnez à chaque flèche un sens et au moins deux informations : le protocole et l'intention. Précisez sync ou async quand c'est utile.

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

La flèche va de l'appelant vers le destinataire. Ne tracez pas de seconde flèche pour la réponse : cela double le nombre de traits sans rien apporter. Si l'ordre des requêtes et des réponses compte, c'est le rôle d'un diagramme de séquence.

4. Regroupez avec des frames

Les groupes forment le deuxième niveau de lecture. Placez les composants dans des frontières qui ont un sens :

• Zones réseau : subnet public, subnet privé, DMZ, réseau on-premise
• Namespaces Kubernetes : payments, platform, observability
• Régions et comptes : eu-central-1, us-east-1, comptes prod et staging
• Frontières de confiance : l'endroit où le trafic venant d'Internet est authentifié

L'imbrication est possible (région > VPC > subnet), mais chaque niveau supplémentaire rend le diagramme plus difficile à lire.

5. Ajoutez une légende

Si une couleur, un style de trait ou une icône a un sens, la légende doit le dire. Un trait pointillé, c'est un message async ? Un cadre rouge, c'est le périmètre PCI ? Ce qui est évident pour la personne qui a dessiné ne l'est pas pour celle qui lit le schéma six mois plus tard.

6. Ajoutez un titre, une date et un propriétaire

Mettez trois informations dans un coin de chaque diagramme : un titre qui dit ce qu'il montre (« Checkout — vue container, prod »), la date de dernière mise à jour et l'équipe propriétaire. Personne ne peut savoir si un diagramme sans date est à jour, et personne ne met à jour un diagramme sans propriétaire.

7. Faites-le relire par quelqu'un qui ne l'a pas dessiné

Montrez le diagramme à quelqu'un qui ne l'a pas dessiné et posez la question écrite au départ. Si la personne trouve la réponse sans vos explications, le diagramme fonctionne. Si vous répétez « ici, je voulais dire… », ajoutez cette explication au diagramme.

Erreurs fréquentes

• Tout mettre dans un seul diagramme. Contexte, déploiement et détails réseau sur une même image : au final, rien n'est lu.
• Flèches sans libellé ou à double sens. On ne sait pas qui appelle qui, alors que c'est justement ce qu'on cherche pendant un incident.
• Niveaux d'abstraction mélangés. Si une boîte s'appelle « Système de paiement » et la voisine « pod Redis », le lecteur perd l'échelle.
• Couleurs non expliquées. Une couleur absente de la légende est soit décorative, soit mal interprétée.
• Ni propriétaire ni date. Un diagramme sur le wiki sans auteur connu finit par devenir une source d'informations fausses.

Garder le diagramme à jour

Un diagramme n'est utile que tant qu'on lui fait confiance. Quelques habitudes aident :

• Rangez le diagramme près de la documentation du système et liez-le depuis le README ou le runbook.
• Ajoutez « diagramme mis à jour ? » à la checklist des pull requests qui modifient l'architecture.
• Conservez une révision avant les gros changements, pour que « à quoi ça ressemblait le trimestre dernier ? » ait une réponse.
• Planifiez une revue récurrente dans le calendrier de l'équipe propriétaire, par exemple une fois par trimestre.

Faire un diagramme d'architecture logicielle dans Archboard

Archboard est un espace de travail d'architecture hébergé pour les équipes plateforme et produit. Les étapes ci-dessus fonctionnent avec n'importe quel outil ; dans Archboard, elles se déroulent ainsi :

1. Connectez-vous. Passez par la page de connexion avec Google ou GitHub. La première connexion crée votre compte et votre organisation ; aucune carte bancaire n'est demandée.
2. Choisissez vos packs. Archboard propose 27 packs intégrés et 223 types de nodes. Pour un premier diagramme, ceux-ci suffisent généralement :
   • C4 Model : Person, Software System, Container, Component, Database et boundaries, pour les vues contexte et container.
   • Kubernetes : Namespace (dessiné comme un frame), Deployment, Pod, Service, Ingress, ConfigMap, Secret, PVC, HPA, NetworkPolicy, etc.
   • Cloud : pour l'infrastructure cloud, avec un node k8s-cluster pour les cartes multi-comptes.
   • Network : pour les zones réseau et les liaisons.
3. Connectez les ports. Les nodes sont des nodes à part entière avec des ports, pas des formes génériques. Tirez une connexion de port à port et annotez-la avec le protocole et l'intention.
4. Regroupez avec des frames. Utilisez le Frame du pack Core pour les zones réseau et les régions, le Namespace Kubernetes pour les namespaces et les boundaries C4 pour la frontière du système.
5. Ajoutez titre et légende. Posez un bloc Markdown ou une Table sur le canvas pour réunir titre, date, propriétaire et légende au même endroit.
6. Partagez. Envoyez le lien de partage public à votre relecteur (avec la marque Archboard en Free). En Pro et Enterprise, vous pouvez intégrer le diagramme dans votre site de documentation via un iframe.
7. Exportez. Exportez en SVG ou PNG (avec filigrane en Free) ; Pro ajoute JPEG, PDF et GIF / WebM animés, le tout sans filigrane. Vous pouvez aussi exporter le document du diagramme en JSON structuré.

Les modifications sont enregistrées automatiquement et chaque diagramme conserve ses révisions : les 5 dernières sur Free, un an d'historique sur Pro et un historique sans limite de durée sur Enterprise. Free inclut tous les packs intégrés, 3 diagrammes et 15 nœuds de diagramme plus 150 notes, textes, autocollants et sujets de carte mentale par diagramme, largement de quoi réaliser un premier diagramme de contexte ; Pro débloque les diagrammes et nœuds illimités pour des cartes de déploiement complètes. Détails sur la page tarifs.

Avant de commencer, parcourez la galerie d'exemples : ouvrez un exemple public et copiez-le dans votre espace de travail avec Utiliser cet exemple (il compte dans votre quota de diagrammes). Pour les spécificités C4 et Kubernetes, consultez les pages cas d'usage C4 et cas d'usage Kubernetes. Les premières idées peuvent aussi naître sur le même canvas : Archboard propose des sticky notes et des mind maps à côté des packs d'architecture.

Checklist et FAQ

Avant de publier :

• Le lecteur et la question sont écrits
• La frontière est claire, les systèmes externes sont des boîtes uniques
• Chaque flèche a un sens et un libellé protocole + intention
• Les groupes montrent de vraies frontières : zones réseau, namespaces, régions
• Légende, titre, date et propriétaire sont présents
• Quelqu'un qui ne l'a pas dessiné a pu répondre à la question

Quelle différence entre un diagramme d'architecture et un logigramme ? Un diagramme d'architecture montre la structure : quels composants existent et comment ils sont reliés. Un logigramme (flowchart) montre les étapes et les points de décision d'un processus. Si l'ordre d'une requête dans le temps compte, utilisez un diagramme de séquence.

Combien de diagrammes faut-il dessiner ? Un par couple lecteur-question. Pour la plupart des systèmes, un diagramme de contexte, un diagramme de containers et un diagramme de déploiement sont un bon début.

Quel outil utiliser ? Un outil qui connaît les concepts que vous dessinez. Archboard fournit les concepts Kubernetes, C4 et cloud sous forme de nœuds prêts à l'emploi avec des ports, pour un diagramme lisible et facile à tenir à jour. Quel que soit votre choix, le vrai test reste de savoir si le diagramme répond à votre question.

Commencez gratuitement — un siège, sans carte bancaire.