Au début d’un projet, l’architecture technique paraît simple à comprendre. Puis les microservices se multiplient, les pipelines CI/CD s’enrichissent, les dépendances s’accumulent, et la lecture d’ensemble devient moins évidente. C’est là qu’un schéma clair fait toute la différence. Le problème, c’est que les outils graphiques classiques sont souvent longs à maintenir et vite déconnectés du code. Mermaid propose une alternative bien plus souple : décrire son architecture en texte, directement dans un fichier Markdown, puis laisser l’outil générer le diagramme. Dans cet article, nous allons voir comment Mermaid permet de visualiser simplement une architecture microservices, un pipeline CI/CD et le fonctionnement d’une API REST avec base de données, tout en restant plus facile à maintenir qu’un schéma produit dans un éditeur classique.

Pourquoi Mermaid simplifie la documentation des architectures techniques

Pour comprendre l’intérêt de Mermaid, il faut repartir d’une réalité très concrète du travail technique : une architecture n’est jamais figée. Même sur un produit relativement simple au départ, le système évolue vite. Une API monolithique peut être découpée en plusieurs services, un proxy ou une gateway peut être ajouté devant les points d’entrée, une base de données unique peut être complétée par un cache ou une file de messages, et la chaîne de déploiement peut intégrer de nouveaux contrôles. À mesure que le projet prend de l’ampleur, les flux deviennent plus nombreux, les dépendances plus fines, et la compréhension globale demande davantage qu’un simple texte descriptif. Dans ce contexte, documenter l’architecture ne consiste pas seulement à produire un schéma au démarrage. Il faut surtout pouvoir le faire vivre. C’est souvent là que les difficultés commencent. Beaucoup d’équipes réalisent un premier diagramme dans un outil graphique, puis le stockent à part, sous forme de fichier image ou de document exporté. Tant que l’architecture reste stable, cela peut suffire. Mais dès que les changements s’enchaînent, la mise à jour devient fastidieuse. Il faut rouvrir le bon fichier source, retrouver la version la plus récente, modifier les blocs, vérifier les alignements, réexporter, puis republier le visuel. À force, le schéma n’est plus synchronisé avec la réalité technique.

Mermaid change cette logique en transformant le diagramme en texte. Cette différence paraît simple, mais elle modifie profondément la manière de documenter. Au lieu de considérer le schéma comme un objet graphique séparé, on le traite comme une ressource versionnable au même titre qu’un fichier de configuration, qu’une spécification technique ou qu’un extrait de code. Il peut être stocké directement dans le dépôt, relu dans une pull request, corrigé en même temps qu’une évolution applicative et affiché dans une documentation Markdown sans passer par un export manuel. Cette approche apporte une cohérence très appréciable dans un environnement Dev ou DevOps. L’équipe n’a plus besoin de sortir de son écosystème habituel pour maintenir ses diagrammes. Le schéma vit dans les mêmes outils que le reste du projet. Il peut être relu avec les mêmes réflexes, mis à jour dans les mêmes cycles de travail, et conservé dans le même historique. Cela réduit fortement la friction documentaire, c’est-à-dire tout ce qui pousse une équipe à remettre à plus tard la mise à jour de sa documentation. Le bénéfice le plus visible concerne la maintenance. Lorsqu’un service change de rôle, qu’un nouveau composant est ajouté ou qu’un flux est redirigé, la modification tient souvent à quelques lignes. On ne déplace pas des boîtes à la souris, on ajuste une relation ou un nom dans un bloc de texte. Cette légèreté favorise des corrections plus fréquentes. Or, une documentation légère à maintenir a beaucoup plus de chances de rester utile dans le temps.

La collaboration y gagne également. Dans un schéma purement graphique, la modification revient souvent à la personne qui maîtrise l’outil utilisé ou qui possède la source la plus à jour. Avec Mermaid, la barrière d’entrée est plus basse pour les profils techniques. Un développeur backend peut corriger un flux d’appel, un ingénieur plateforme peut enrichir la partie infrastructure, un architecte peut proposer un nouveau découpage de services, et chacun peut le faire sous forme de texte. Cette simplicité facilite aussi les revues collectives : les changements sont plus lisibles dans un diff qu’au travers de deux captures d’écran presque identiques.

Un autre point fort tient à l’intégration dans les outils de documentation déjà utilisés par les équipes. Quand le diagramme est écrit en Mermaid, il peut être intégré dans un README, dans une base de connaissances, dans une documentation interne ou dans un portail technique. Cela permet de rapprocher les explications et leur représentation visuelle. Au lieu d’avoir un texte d’un côté et un schéma rangé dans un autre dossier, on centralise l’information. Cette proximité améliore la lisibilité et réduit le risque d’incohérence entre le contenu rédigé et le diagramme affiché. Il est aussi important de préciser que cette simplicité n’enferme pas Mermaid dans un rôle minimaliste. L’outil est très utile pour les diagrammes de flux, mais pas uniquement. Il peut aussi servir à montrer une séquence d’interactions, une frise de planification, une représentation de branches Git, un graphe de dépendances ou encore des logiques de cycle de vie. Pour la documentation d’architecture, cela permet de multiplier les niveaux de lecture. Une vue globale peut présenter les grands composants d’un système, tandis qu’une vue plus détaillée peut expliquer un flux d’authentification, un traitement asynchrone ou un pipeline CI/CD.

Voici un exemple très simple de structure textuelle avec Mermaid :

graph TD
Client --> API_Gateway
API_Gateway --> Auth_Service
API_Gateway --> Product_Service
Product_Service --> Database

Avec seulement quelques lignes, on obtient déjà une lecture claire d’un scénario fréquent. Le client ne dialogue pas directement avec tous les composants. Il passe par une gateway, qui distribue ensuite la requête entre plusieurs services spécialisés. L’authentification est isolée dans un service dédié, tandis qu’un service métier s’appuie sur une base de données. Cette écriture compacte montre bien la force de Mermaid : Représenter rapidement la structure fonctionnelle d’un système sans passer du temps sur des éléments de présentation secondaires. Dans les faits, cette sobriété est souvent un avantage. Un schéma trop chargé, trop décoré ou trop précis sur des aspects visuels peut ralentir la lecture au lieu de la faciliter. Dans un contexte technique, ce que l’on cherche en priorité, c’est de comprendre qui parle à qui, par où passe une requête, quelle couche dépend d’une autre, et où se trouvent les points sensibles du système. Mermaid favorise cette lecture orientée structure. Il pousse naturellement à clarifier les relations avant d’embellir le rendu. Cela le rend particulièrement intéressant pour les architectures microservices. Dans ce type d’environnement, le nombre de composants augmente vite. On doit visualiser les points d’entrée, les services transverses, les bases de données, les brokers de messages, les services externes, parfois les caches et les tâches asynchrones. Avec un outil purement graphique, le schéma peut devenir lourd à maintenir. Avec Mermaid, il est plus facile de séparer les vues : un diagramme général pour la cartographie, un autre pour un domaine métier, un autre encore pour un flux précis comme le paiement ou la gestion des notifications.

La durée de vie du projet est également un facteur important. Une architecture n’est pas consultée uniquement au moment de sa conception. Elle sert aussi à accompagner de nombreuses situations concrètes : l’arrivée d’un nouveau collaborateur, une revue d’incident, un chantier de refactoring, une analyse d’impact avant évolution, la préparation d’un audit technique, la documentation d’une API ou la rationalisation d’un découpage fonctionnel. Dans toutes ces situations, la valeur du diagramme dépend de son actualité. Un schéma très détaillé mais plus à jour est souvent moins utile qu’un schéma simple, précis et correctement maintenu. Mermaid s’inscrit justement dans cette logique de documentation vivante. Il ne cherche pas à remplacer tous les outils de diagramme, ni à produire les visuels les plus sophistiqués possibles. Il répond à un besoin précis : rendre la documentation d’architecture plus facile à créer, à partager et à faire évoluer. Cette orientation le rend particulièrement adapté aux équipes qui privilégient des supports opérationnels, lisibles rapidement et suffisamment souples pour accompagner les changements continus du système.

On peut aussi voir Mermaid comme un outil d’alignement collectif. Quand une équipe décrit son architecture sous forme textuelle, elle est amenée à nommer clairement ses composants, à expliciter ses relations et à simplifier sa façon de raconter le système. Cet effort d’écriture a une valeur en soi. Il améliore la qualité de la documentation, mais aussi souvent la qualité de la réflexion architecturale. En cherchant à produire un schéma compréhensible, on affine parfois le découpage des responsabilités ou l’expression des flux. Enfin, Mermaid apporte un gain de cohérence méthodologique. Dans beaucoup d’équipes modernes, tout ou presque est déjà traité comme du texte : le code, l’infrastructure, les pipelines, les fichiers de configuration, les tests, les notes techniques, les tickets de mise en œuvre. Ajouter les diagrammes à cette logique permet d’unifier encore davantage la manière de travailler. La documentation visuelle cesse d’être un élément à part, plus difficile à entretenir que le reste. Elle devient une composante naturelle du projet.

Illustrer une architecture microservices et un pipeline CI/CD avec Mermaid

Les architectures microservices constituent un excellent terrain d’application pour Mermaid, car elles reposent sur une logique de découpage qui complexifie rapidement la lecture d’ensemble. Tant qu’une application reste monolithique, il est encore possible de conserver une vision mentale relativement claire des interactions internes. Mais dès que le système est réparti entre plusieurs services spécialisés, cette compréhension devient plus exigeante. Il faut identifier le point d’entrée principal, distinguer les services métier des composants transverses, comprendre les mécanismes d’authentification, localiser les bases de données, visualiser les flux synchrones, repérer les traitements asynchrones et intégrer les services tiers dans la représentation globale. Sans schéma, ces informations sont souvent dispersées entre des documents techniques, des tickets, des connaissances informelles ou la mémoire des membres historiques de l’équipe. Dans ce contexte, Mermaid permet de remettre de l’ordre et de la lisibilité. L’intérêt n’est pas uniquement de produire un diagramme, mais de construire une représentation progressive et maintenable de l’architecture. On peut commencer par une vue générale qui montre les grands composants du système, puis ajouter des schémas plus ciblés sur un domaine, un flux métier, un point d’intégration ou un mécanisme de déploiement. Cette logique est particulièrement adaptée aux microservices, car une architecture de ce type ne se comprend pas bien à travers un seul schéma massif. Elle se comprend mieux par couches de lecture.

Pourquoi Mermaid est pertinent pour représenter une architecture microservices

Dans une architecture microservices, chaque composant a un rôle précis, mais l’ensemble forme un réseau d’interactions parfois dense. Un service de catalogue peut dialoguer avec sa propre base, un service de commande peut publier des événements, un service d’authentification peut gérer les identités, une API gateway peut centraliser les entrées, tandis qu’un frontend orchestre l’expérience utilisateur. À cela peuvent s’ajouter un cache, un système de messagerie, des connecteurs vers des solutions externes, des outils d’observabilité, des workers en arrière-plan ou encore des mécanismes de notification. Mermaid est utile dans cette situation parce qu’il permet de représenter les liens essentiels sans alourdir la lecture. On ne commence pas par une préoccupation de design visuel, mais par une préoccupation de structure. Cela pousse naturellement à répondre aux bonnes questions : quels sont les composants principaux, quelles dépendances existent entre eux, quels flux doivent être montrés, et quel niveau de détail est réellement utile pour comprendre l’ensemble. Cette approche est très précieuse dans un environnement technique où l’objectif d’un schéma est d’éclairer rapidement le fonctionnement global. Autre point important : Mermaid permet de documenter une architecture microservices au fil de l’eau. Lorsqu’un nouveau service apparaît, lorsqu’une responsabilité change de place, lorsqu’un flux asynchrone remplace un appel direct ou lorsqu’une intégration externe est ajoutée, la documentation peut évoluer en même temps que le système. Cette capacité de mise à jour fréquente est particulièrement importante dans les architectures distribuées, car elles changent souvent plus vite que la documentation traditionnelle.

Comment Mermaid aide à construire une vue d’ensemble progressive

L’un des pièges les plus fréquents dans la documentation d’architecture consiste à vouloir tout montrer dans un seul diagramme. Avec une architecture microservices, cette tentation mène souvent à une représentation confuse. Trop de blocs, trop de flèches, trop de détails et, au final, une lecture laborieuse. Mermaid permet justement d’adopter une approche plus progressive. On peut produire d’abord une cartographie simple des briques majeures, puis détailler ensuite certains sous-ensembles dans d’autres schémas. Cette progression est très utile dans une documentation technique bien structurée. Une première vue sert à comprendre comment le système est composé. Une deuxième peut détailler un domaine fonctionnel précis, comme la gestion des paiements ou le traitement des notifications. Une troisième peut se concentrer sur un flux spécifique, par exemple le parcours d’une commande. Cette hiérarchie des schémas évite de noyer le lecteur sous une avalanche d’informations. Mermaid se prête bien à cette logique, car créer plusieurs diagrammes courts est généralement plus simple que maintenir un grand schéma graphique centralisé. Cette modularité améliore la compréhension et facilite la maintenance. Chaque diagramme a un objectif précis, ce qui renforce sa valeur documentaire.

Exemple Mermaid d’une architecture microservices réaliste

Prenons un exemple d’architecture microservices assez courant pour une plateforme applicative. L’idée n’est pas de reproduire un système complet dans ses moindres détails, mais de montrer comment quelques lignes de Mermaid suffisent à rendre une architecture déjà très parlante :

graph LR
Utilisateur --> Frontend
Frontend --> API_Gateway
API_Gateway --> Auth_Service
API_Gateway --> Catalog_Service
API_Gateway --> Order_Service
API_Gateway --> Payment_Service
Order_Service --> Order_DB
Catalog_Service --> Catalog_DB
Auth_Service --> User_DB
Payment_Service --> External_Payment_Provider
Order_Service --> Message_Broker
Message_Broker --> Notification_Service
Notification_Service --> Email_Service

Ce schéma est compact, mais il transmet déjà beaucoup d’informations utiles. On comprend d’abord que l’utilisateur n’accède pas directement aux services métier. Il passe par une interface frontend, qui elle-même s’appuie sur une API gateway. Cette gateway joue un rôle de centralisation et de distribution des requêtes. Elle dirige ensuite les appels vers plusieurs services spécialisés, ce qui montre immédiatement le découpage fonctionnel du système. On voit aussi que les responsabilités sont séparées de manière cohérente. Le service d’authentification gère les enjeux liés aux utilisateurs et à l’accès. Le service de catalogue se concentre sur les données produits. Le service de commande pilote le traitement métier des achats. Le service de paiement communique avec un prestataire externe. Chaque bloc raconte une responsabilité claire, ce qui est exactement ce qu’une architecture microservices cherche généralement à obtenir. Le schéma met également en évidence les dépendances de données. Certains services disposent de leur propre base, ce qui renforce l’idée d’autonomie. Cette autonomie est souvent au cœur des architectures microservices, car elle limite les couplages forts et facilite l’évolution indépendante des domaines. En parallèle, le flux entre le service de commande et le broker de messages révèle une dimension asynchrone. Cela montre que le système ne repose pas uniquement sur des appels synchrones de type requête-réponse, mais intègre aussi des événements pour déclencher d’autres traitements, ici des notifications envoyées par email. Avec un diagramme de cette taille, l’équipe peut déjà expliquer une grande partie de son architecture à un nouveau membre, à un interlocuteur technique externe ou à un responsable de domaine. C’est une démonstration très concrète de l’efficacité de Mermaid : raconter rapidement une architecture réaliste avec peu de syntaxe.

Quels bénéfices Mermaid apporte au quotidien dans une équipe technique

Une représentation de ce type n’est pas seulement utile pour illustrer un document. Elle sert au quotidien. Lors de l’onboarding d’un nouveau développeur, elle permet de comprendre où entre une requête, quels services sont impliqués, quelles bases sont concernées et quels flux sont secondaires ou asynchrones. Cela réduit le temps nécessaire pour se repérer dans le système. En réunion d’architecture, le schéma devient un support de discussion. Il aide à débattre du découpage des responsabilités, à remettre en question certaines dépendances, à identifier des zones de couplage excessif ou à envisager l’extraction d’un nouveau service. Le simple fait d’avoir une représentation claire change souvent la qualité des échanges, car chacun parle à partir d’un référentiel partagé. Lors d’une revue d’incident, Mermaid est tout aussi utile. Si un service tombe, si une file de messages sature, si un prestataire externe devient indisponible ou si un problème de latence apparaît, le schéma aide à visualiser les impacts potentiels. Il devient alors un outil d’analyse, et pas seulement un élément de documentation théorique. Dans une documentation produit ou une base de connaissance interne, cette même vue peut servir d’introduction. Elle permet d’expliquer la structure générale sans imposer tout de suite des détails de code, de configuration ou d’infrastructure. C’est particulièrement précieux lorsque le lecteur n’a pas encore besoin de comprendre l’implémentation complète mais cherche d’abord à saisir l’organisation du système.

Pourquoi Mermaid rend les schémas microservices plus lisibles

Mermaid présente aussi un avantage plus subtil, mais très important : Il pousse à simplifier le discours technique. Quand un schéma est écrit sous forme de texte, l’auteur est souvent amené à sélectionner ce qui compte réellement. Il évite plus facilement les éléments décoratifs, les alignements excessivement travaillés, les détails graphiques secondaires ou les annotations redondantes. Le résultat est souvent plus sobre, mais aussi plus utile. Dans le cas des microservices, cette sobriété est bénéfique. Une architecture distribuée peut vite devenir illisible si l’on cherche à tout représenter dans un même visuel très enrichi. À l’inverse, un diagramme Mermaid bien conçu met l’accent sur les relations structurantes : les points d’entrée, les services métier, les dépendances de données, les flux d’événements et les intégrations majeures. Le lecteur identifie plus vite les mécanismes importants, ce qui renforce la valeur pédagogique du schéma. Cette lisibilité n’empêche pas d’aller plus loin. Au contraire, elle prépare le terrain pour des diagrammes complémentaires. Une vue générale épurée peut être suivie de vues plus spécialisées, sans que la documentation perde sa cohérence. Mermaid permet ainsi d’alterner entre synthèse et détail.

Pourquoi Mermaid est aussi très utile pour les pipelines CI/CD

Le même raisonnement s’applique aux pipelines CI/CD. Dans de nombreuses équipes, la chaîne d’intégration et de déploiement continu existe, fonctionne et se raffine progressivement, mais elle n’est pas toujours facilement lisible dans son ensemble. Chaque profil en connaît souvent une partie. Les développeurs savent qu’un commit déclenche des jobs. Les ingénieurs DevOps connaissent la logique de build, d’image et de déploiement. Les responsables qualité maîtrisent les étapes de test. Les équipes sécurité savent où interviennent les scans ou les contrôles. Pourtant, il manque parfois une vue simple de l’enchaînement global. Or, un pipeline CI/CD est lui aussi une architecture de flux. Il relie des événements, des validations, des artefacts, des environnements et des conditions de passage. À ce titre, il gagne énormément à être représenté visuellement. Mermaid permet précisément de transformer une suite d’étapes parfois abstraite en un chemin de lecture clair.

Exemple Mermaid d’un pipeline CI/CD lisible

Voici un exemple de pipeline CI/CD décrit avec Mermaid :

graph TD
Developer_Push --> Source_Repository
Source_Repository --> CI_Pipeline
CI_Pipeline --> Install_Dependencies
Install_Dependencies --> Run_Unit_Tests
Run_Unit_Tests --> Static_Code_Analysis
Static_Code_Analysis --> Build_Docker_Image
Build_Docker_Image --> Push_Registry
Push_Registry --> Deploy_Staging
Deploy_Staging --> Run_Integration_Tests
Run_Integration_Tests --> Manual_Approval
Manual_Approval --> Deploy_Production
Deploy_Production --> Monitoring

Ce diagramme rend immédiatement la chaîne intelligible. On voit qu’un push déclenché par un développeur alimente le dépôt source, lequel active ensuite le pipeline. Les dépendances sont installées, les tests unitaires sont lancés, une analyse statique intervient, puis l’image applicative est construite. Cette image est ensuite poussée vers un registre, déployée sur un environnement de staging, testée plus en profondeur, soumise à une validation humaine avant d’être promue en production, puis surveillée. Sans représentation visuelle, expliquer cette séquence demanderait un texte plus long, plus linéaire et souvent moins mémorisable. Le diagramme, au contraire, condense la logique du pipeline sans la rendre opaque. Il montre l’ordre des opérations, leur dépendance et les points de contrôle principaux. Dans une documentation technique, cette synthèse visuelle est particulièrement efficace.

Comment Mermaid met en valeur les enjeux qualité, sécurité et déploiement

Pour une équipe DevOps, un pipeline n’est pas uniquement une suite d’étapes automatisées. C’est aussi un support de gouvernance technique. Il montre où sont placés les garde-fous, à quel moment la qualité est vérifiée, où la sécurité peut intervenir, comment les artefacts sont promus et quels mécanismes empêchent un déploiement trop risqué. Mermaid permet d’exposer cette logique de manière très pédagogique. Dans l’exemple précédent, plusieurs éléments peuvent être lus sous cet angle. Les tests unitaires jouent un rôle de validation rapide. L’analyse statique ajoute une couche de contrôle sur la qualité du code. La construction de l’image montre la préparation de l’artefact déployable. Le passage par un registre matérialise la logique de stockage centralisé. Le déploiement en staging permet une validation sur un environnement proche de la production. Les tests d’intégration vérifient que le système fonctionne dans un cadre plus réaliste. Enfin, l’approbation manuelle introduit un verrou décisionnel avant la production. Visualiser ces étapes est très utile pour l’équipe, mais aussi pour d’autres interlocuteurs : responsables techniques, chefs de projet, nouveaux arrivants ou auditeurs internes. Un schéma Mermaid de pipeline permet de montrer rapidement que le processus de livraison ne repose pas sur une succession opaque de scripts, mais sur une chaîne structurée avec des contrôles clairement identifiables.

Comment Mermaid aide à représenter des variantes de pipeline

Dans la pratique, un pipeline CI/CD est rarement totalement linéaire. Il peut varier selon les branches, les environnements, le type d’application ou la stratégie de déploiement choisie. Certaines équipes déclenchent des étapes différentes entre une branche de fonctionnalité, une branche de recette et la branche principale. D’autres utilisent des déploiements conditionnels, des validations supplémentaires, des scans de sécurité avancés, des promotions d’artefacts entre environnements, ou encore des stratégies de mise en production comme le blue/green ou le canary. Mermaid est intéressant ici parce qu’il permet de représenter ces variantes sans entrer dans une lourdeur graphique excessive. On peut créer un schéma spécifique pour la branche principale, un autre pour le flux de validation d’une release, ou encore un troisième pour montrer le chemin de promotion d’un artefact de l’environnement de test vers la production. Cela aide à distinguer clairement les parcours sans surcharger un schéma unique. Cette souplesse est particulièrement utile dans les contextes où le pipeline lui-même devient un sujet de discussion stratégique. Une équipe peut comparer plusieurs approches, faire évoluer sa chaîne de livraison ou documenter une transition entre deux mécanismes de déploiement. Mermaid apporte alors un cadre simple pour expliciter ces transformations.

Pourquoi associer Mermaid pour les microservices et Mermaid pour le CI/CD dans une même documentation

L’un des usages les plus intéressants consiste à documenter dans le même espace l’architecture applicative et l’architecture de livraison. D’un côté, les schémas microservices montrent comment le système est composé : les services, les bases de données, les brokers, les points d’entrée, les intégrations. De l’autre, les schémas CI/CD montrent comment ce système est construit, testé, validé et déployé. Réunir ces deux visions dans une documentation cohérente crée un langage commun au sein de l’équipe. Cette double lecture a beaucoup de valeur, car dans la réalité quotidienne, ces deux dimensions sont intimement liées. La façon dont les services sont découpés influence souvent la manière dont ils sont buildés, testés et livrés. À l’inverse, la stratégie de déploiement peut avoir un impact sur certaines décisions architecturales. Une architecture très distribuée, par exemple, suppose souvent des pipelines multiples, des tests d’intégration plus structurés et une attention particulière à l’observabilité et à la promotion des artefacts. En documentant à la fois le système et sa chaîne de livraison avec Mermaid, l’équipe évite de traiter séparément deux sujets pourtant interdépendants. Elle gagne en cohérence, en lisibilité et en capacité de transmission. Cela facilite la compréhension globale du produit, aussi bien pour les profils orientés développement que pour ceux davantage tournés vers l’exploitation, la plateforme ou la qualité logicielle.

Comment Mermaid renforce la culture documentaire des équipes Dev et DevOps

Au-delà de la simple production de schémas, Mermaid contribue aussi à installer une meilleure culture de la documentation. En rendant l’écriture des diagrammes plus accessible, il favorise leur mise à jour régulière. En rapprochant les schémas du dépôt de code, il augmente leur visibilité. En simplifiant la contribution, il ouvre la documentation à plusieurs profils techniques. Et en encourageant des vues courtes et ciblées, il améliore la qualité pédagogique de l’ensemble. Pour des équipes Dev et DevOps, c’est un point loin d’être anecdotique. Une bonne documentation d’architecture n’est pas seulement un luxe ou un livrable de fin de projet. C’est un outil de travail. Elle sert à expliquer, à transmettre, à décider, à diagnostiquer, à faire évoluer et à sécuriser la compréhension du système. Mermaid s’inscrit très bien dans cette logique parce qu’il réduit le coût de production et de maintenance des représentations visuelles. Illustrer une architecture microservices et un pipeline CI/CD avec Mermaid, c’est donc bien plus qu’ajouter quelques diagrammes dans une documentation. C’est structurer la manière dont l’équipe raconte son système et sa livraison. C’est rendre visibles des relations qui, autrement, resteraient diffuses. C’est aussi offrir à tous les membres du projet un support commun pour mieux comprendre ce qui compose l’application et comment elle évolue jusqu’en production.

Comparer Mermaid à Draw.io et appliquer la méthode à un cas concret d’api rest avec base de données

Comparer Mermaid à Draw.io est intéressant, non pas pour déclarer un vainqueur universel, mais pour comprendre dans quels contextes chaque approche est la plus pertinente. Draw.io est un outil graphique souple, très apprécié pour créer des schémas personnalisés, des cartographies détaillées ou des représentations plus riches visuellement. Il permet un contrôle précis des formes, des alignements, des couleurs et des annotations. Pour des supports de présentation, des livrables clients ou des schémas demandant une forte dimension visuelle, il peut être très adapté. Mermaid, de son côté, mise sur une philosophie différente. Son point fort n’est pas la liberté graphique totale, mais la rapidité de production, la maintenabilité et l’intégration naturelle dans une documentation technique versionnée. Là où Draw.io implique un travail de composition visuelle, Mermaid invite à exprimer les relations essentielles. Cette différence de posture est fondamentale. Dans un environnement où les diagrammes doivent être souvent ajustés, relus par plusieurs personnes et stockés au plus près du code, Mermaid devient très pratique.

En réalité, beaucoup d’équipes peuvent utiliser les deux de manière complémentaire. Mermaid peut servir à la documentation du quotidien, celle qu’on consulte et qu’on modifie souvent. Draw.io peut intervenir lorsqu’il faut produire un schéma plus scénarisé pour un comité, un dossier d’architecture ou une présentation métier. Le bon choix dépend du rythme de changement, du public visé et du niveau de personnalisation attendu. Pour mieux comprendre la valeur concrète de Mermaid, prenons maintenant un cas pratique : une API REST connectée à une base de données. C’est un scénario classique, mais justement très utile pour montrer la force d’une représentation simple et évolutive. Envisageons une application de gestion de commandes. Un client envoie une requête HTTP à une API REST. Cette API est protégée par un mécanisme d’authentification. Les requêtes valides sont routées vers un service métier. Le service interagit avec une base de données relationnelle et peut, selon le besoin, envoyer un événement à un service de journalisation ou à une file de messages. Voici une première vue simple :

graph TD
Client --> Load_Balancer
Load_Balancer --> REST_API
REST_API --> Auth_Middleware
Auth_Middleware --> Order_Controller
Order_Controller --> Order_Service
Order_Service --> PostgreSQL
Order_Service --> Cache
Order_Service --> Event_Bus
Event_Bus --> Logging_Service

Ce diagramme met déjà en évidence plusieurs couches. Le point d’entrée réseau n’est pas directement l’API, mais un répartiteur de charge. L’API passe ensuite par une couche d’authentification. Le contrôleur reçoit les requêtes, délègue au service métier, et ce dernier interagit avec la base de données, éventuellement avec un cache, puis peut publier des événements. Une représentation comme celle-ci est utile pour expliquer le fonctionnement global à une personne qui découvre le cahier des charges d’une application native. On peut aussi produire une vue davantage centrée sur le cycle de vie d’une requête, par exemple lorsqu’un utilisateur crée une commande :

sequenceDiagram
Client->>API: POST /orders
API->>Auth_Service: vérifier le jeton
Auth_Service-->>API: autorisation valide
API->>Order_Service: créer la commande
Order_Service->>PostgreSQL: enregistrer la commande
PostgreSQL-->>Order_Service: identifiant créé
Order_Service->>Event_Bus: publier l’événement order_created
Event_Bus->>Notification_Service: transmettre l’événement
Notification_Service-->>Client: confirmation envoyée

Cette deuxième lecture complète la première. Le schéma d’architecture montre la structure statique du système. Le diagramme de séquence montre le comportement dynamique lors d’un cas d’usage précis. Ensemble, ces représentations renforcent énormément la qualité de la documentation. Dans un contexte DevOps, ce cas concret peut encore être enrichi avec la chaîne de livraison associée à l’API :

graph LR
Code_Commit --> Unit_Tests
Unit_Tests --> Build_API_Image
Build_API_Image --> Security_Scan
Security_Scan --> Push_Registry
Push_Registry --> Deploy_Test
Deploy_Test --> API_Functional_Tests
API_Functional_Tests --> Deploy_Production

On relie ainsi l’architecture applicative à la manière dont elle est testée et déployée. Cette continuité documentaire est précieuse. Elle permet de comprendre non seulement comment l’API fonctionne, mais aussi comment elle arrive en environnement de test puis en production. Pour une équipe technique, cette cohérence est un vrai facteur de clarté. Autre avantage : Mermaid encourage à documenter au bon niveau. Pour une API REST, on peut choisir de ne montrer que les composants majeurs dans le README principal, puis détailler certains flux métier dans des pages dédiées. On évite ainsi l’écueil du diagramme unique qui tente de tout montrer et finit par devenir illisible. Une documentation bien pensée avec Mermaid repose souvent sur plusieurs schémas courts, chacun associé à un objectif précis : vue d’ensemble, flux métier, pipeline de livraison, dépendances externes, stratégie de déploiement, ou parcours d’authentification. Cette méthode est particulièrement efficace pour les équipes qui veulent industrialiser leur documentation. Lorsqu’un nouveau service apparaît, on peut mettre à jour le diagramme correspondant dans la même pull request que le code. Lorsqu’une base change, un diff Git montre immédiatement l’évolution de l’architecture. Lorsqu’un pipeline se renforce avec une étape de sécurité ou des tests complémentaires, la documentation évolue dans le même mouvement. Cette proximité entre réalité technique et représentation visuelle réduit fortement l’écart entre ce qui est implémenté et ce qui est expliqué. En savoir plus sur Mermaid : Rendez-vous ici.