TECHNOLOGIES
Mermaid, nos diagrammes construits dans le code
Mermaid est un outil open source qui génère des diagrammes à partir d'une syntaxe texte simple. Flowcharts, séquences, Gantt, entités : tout se décrit en quelques lignes et se versionne avec Git comme n'importe quel fichier source.
Chez SmartBooster, Mermaid est notre référence pour documenter les workflows, les échanges entre systèmes et les architectures de données, directement dans nos dépôts GitLab.
PRÉSENTATION
Qu'est-ce que Mermaid ?
Mermaid est une bibliothèque JavaScript open source qui génère des diagrammes à partir de définitions textuelles. Plutôt que de dessiner avec la souris dans un outil dédié, on décrit le diagramme en quelques lignes et Mermaid produit le rendu SVG.
Cette approche change fondamentalement la relation entre le code et la documentation : le schéma vit dans le même dépôt Git que le code source, il est révisé lors des code reviews et son historique de modification est consultable avec git log ou git blame.
GitLab et GitHub rendent nativement les blocs Mermaid dans les fichiers Markdown. Il suffit d'encadrer la syntaxe dans un bloc ```mermaid dans un README, un wiki ou une merge request pour obtenir un schéma rendu directement dans l'interface.
POURQUOI MERMAID
Ce qui en fait notre outil de diagrammes de référence
Mermaid résout le problème classique de la documentation qui vieillit mal : un schéma qui vit dans le code ne peut pas se désynchroniser du logiciel qu'il décrit.
Diagrammes versionnés avec Git
Un schéma Mermaid est un fichier texte. Il vit dans le dépôt aux côtés du code, chaque modification est tracée, commentée et réversible comme n'importe quel fichier source.
Éditeur live pour prototyper
Mermaid Live Editor permet de construire et tester un diagramme instantanément dans le navigateur. Pas d'installation, rendu en temps réel avec coloration syntaxique et suggestions.
Nombreux types de diagrammes
Flowchart, séquence, Gantt, classes, entités-relations, états, quadrant : un seul outil couvre l'essentiel des besoins de documentation technique et fonctionnelle.
Rendu natif dans GitLab et GitHub
Les blocs Mermaid dans les fichiers Markdown sont rendus automatiquement par GitLab et GitHub. Pas d'export d'image, pas de fichier annexe à maintenir en parallèle du code.
Documentation toujours à jour
Le schéma évolue avec le code dans le même commit. Il ne peut pas se désynchroniser d'un wiki ou d'une présentation externe mise à jour manuellement.
Intégrable dans les logiciels
Mermaid est une bibliothèque JavaScript : elle peut être embarquée dans une application web pour générer des diagrammes dynamiques à partir des données métier en temps réel.
NOTRE USAGE
Comment nous utilisons Mermaid chez SmartBooster
Nous intégrons Mermaid à toutes les étapes du projet : conception avec le client, documentation technique des échanges entre systèmes, modélisation des données et suivi de planning.
Validation des workflows avant développement
Modéliser le processus métier avec le client en flowchart pour valider la logique complète avant d'écrire la première ligne de code. Les zones d'ambiguïté remontent naturellement à la relecture du schéma.
Séquences d'échanges entre systèmes
Diagrammes de séquence pour documenter les appels API, les webhooks et les synchronisations entre services. Chaque acteur, chaque message et chaque condition sont formalisés dans un schéma partagé.
Architecture de données
Diagrammes entités-relations pour concevoir ou documenter le schéma de base de données. Le modèle est lisible par les développeurs comme par les responsables métier qui valident les entités.
Planning et jalons projet
Diagrammes Gantt pour visualiser les phases d'un projet et communiquer le planning aux parties prenantes. Le schéma vit dans le dépôt et reflète l'avancement réel à chaque mise à jour.
EN PRATIQUE
Mermaid au quotidien dans nos projets
De la conception initiale à la documentation continue, Mermaid accompagne chaque phase du développement avec des schémas lisibles par tous.
Concevoir et valider les workflows avec le client
Avant d'écrire la première ligne de code, nous modélisons le processus métier en flowchart Mermaid avec le client. Chaque étape, chaque condition, chaque acteur est positionné dans le schéma.
Cette étape fait remonter naturellement les zones d'ambiguïté : un branchement non prévu, un cas limite oublié, une validation manquante. Corriger un schéma prend 5 minutes, corriger du code prend des jours.
Le diagramme validé entre dans le dépôt Git et devient la référence partagée entre l'équipe technique et le client tout au long du projet.
L'éditeur live pour construire les schémas
Mermaid Live Editor est l'outil de référence pour créer et tester un diagramme en temps réel dans le navigateur. La syntaxe s'écrit à gauche, le rendu s'affiche immédiatement à droite.
L'éditeur intègre la coloration syntaxique, la détection d'erreurs et une galerie d'exemples pour démarrer rapidement sur chaque type de diagramme. Il permet aussi d'exporter en SVG ou PNG pour les échanges avec les parties prenantes.
Une fois le schéma finalisé dans l'éditeur, le code texte est directement copié dans le fichier Markdown ou le fichier dédié du dépôt Git. Aucune conversion, aucun fichier binaire à gérer.
Documentation des échanges entre systèmes
Les diagrammes de séquence Mermaid sont notre format de référence pour documenter les intégrations : appels API, webhooks, synchronisations entre services, authentification OAuth.
Chaque acteur (navigateur, serveur, service tiers, base de données) est un participant dans le schéma. Les messages, les conditions et les boucles sont formalisés explicitement, ce qui permet de valider la logique avant l'implémentation.
Ces schémas vivent dans le README de l'intégration ou dans le wiki GitLab du projet. Ils sont mis à jour dans le même commit que le code et font l'objet d'une revue lors des merge requests.
Appels API et webhooks
Documenter l'ordre des échanges, les codes de retour attendus et les cas d'erreur dans un schéma de séquence lisible.
Flux d'authentification
Modéliser les étapes OAuth, SSO ou JWT pour valider la logique de sécurité avant tout développement.
Synchronisation de données
Visualiser les lectures, écritures et transformations entre services pour détecter les doublons ou les incohérences de flux.
Pour aller plus loin
Documentation utile
Référence complète de la syntaxe, liste des types de diagrammes et guide de démarrage.
Éditeur en ligne pour créer et tester des diagrammes Mermaid en temps réel, sans installation.
Pour aller plus loin
Approfondir votre réflexion
Mermaid tire tout son intérêt quand les schémas sont versionnés avec Git : historique des modifications, revue dans les merge requests.
GitLab rend nativement les blocs Mermaid dans les README, wikis et issues. Les schémas vivent dans le dépôt sans outil externe.
Mermaid est intégré à notre processus de conception : chaque workflow validé en schéma devient une spécification fiable pour le développement.