Au-delà des images statiques : débloquer la puissance du Diagramme-as-Code avec Mermaid et les outils d’IA

La crise de la documentation

Toute équipe d’ingénierie connaît cette douleur. Vous passez des semaines à concevoir une belle architecture de microservices, en créant méticuleusement des diagrammes Visio qui impressionnent les parties prenantes. Six mois plus tard, le système a évolué : de nouveaux services ont été ajoutés, des bases de données ont été migrées, des points de terminaison d’API ont été dépréciés, mais le diagramme est figé dans le temps. C’est un reliquat. Un mensonge, même.

C’est ce qu’on appelle la « pourriture de la documentation », et c’est le tueur silencieux de la productivité en ingénierie. Lorsque les diagrammes mentent, les développeurs les ignorent. Lorsque les développeurs ignorent la documentation, les connaissances tribales prennent le dessus. Lorsque la seule personne qui connaît le système part, vous vous retrouvez avec une base de code complexe et aucune carte.

Diagramme-as-Code (DaC) est la solution. Et au cœur de celle-ci se trouve Mermaid, l’outil de diagrammation basé sur JavaScript qui transforme du texte brut en visuels magnifiques.

La philosophie fondamentale : traiter les diagrammes comme du logiciel

Le changement fondamental avec le Diagramme-as-Code consiste à traiter vos diagrammes avec la même rigueur que votre code d’application. Cela signifie :

1. Le contrôle de version est la norme

Lorsque votre diagramme est un fichier .mermaid, il vit dans votre dépôt Git aux côtés de votre code source. Chaque modification est suivie. Vous pouvez git blame pour voir qui a ajouté ce nouveau service, git diff pour examiner les modifications avant de fusionner, et revenir à n’importe quel état précédent.

gitGraph
    commit id: "Architecture initiale"
    commit id: "Ajout du service utilisateur"
    branch feature/order-service
    commit id: "Service de commande v1"
    commit id: "Ajout de la passerelle de paiement"
    checkout main
    merge feature/order-service
    commit id: "Mise à jour de la passerelle API"

Exemple : Visualiser l’historique Git de votre diagramme lui-même en utilisant la syntaxe Git Graph de Mermaid

2. Relectures de code pour les diagrammes

Les demandes de fusion ne sont plus réservées au code uniquement. Lorsqu’un développeur propose un nouveau service ou modifie un flux de données, cette modification apparaît comme une différence lisible dans la demande de fusion. Les relecteurs peuvent commenter le diagramme lui-même, garantissant que les décisions architecturales sont discutées et approuvées avant leur fusion.

3. Intégration dans les pipelines CI/CD

Vos diagrammes peuvent être générés et validés automatiquement dans votre pipeline. Imaginez une action GitHub qui :

• Rend tous les diagrammes Mermaid en PNG/SVG

• Les télécharge vers votre site de documentation

• Échoue la construction si une syntaxe Mermaid invalide est détectée

flowchart LR
    A[Développeur pousse le code] --> B[Exécution du pipeline CI]
    B --> C[Exécution des tests]
    B --> D[Affichage des diagrammes Mermaid]
    D --> E{Syntaxe valide ?}
    E -->|Oui| F[Téléchargement vers la documentation]
    E -->|Non| G[Échec de la construction et alerte à l'équipe]
    F --> H[Déploiement de l'application]
    G --> I[Le développeur corrige la syntaxe]
    I --> A

Exemple : Un flux de travail CI/CD pour la validation et le déploiement de diagrammes

Mermaid en action : Exemples concrets

Explorons les types de diagrammes pris en charge par Mermaid avec des exemples pratiques et concrets.

Exemple 1 : Architecture de microservices (diagramme de flux)

Il s’agit du cas d’utilisation le plus courant : visualiser la manière dont vos services communiquent.

flowchart TB
    sous-graphique "Couche client"
        MobileApp[Application mobile]
        WebApp[Application web]
    fin

    sous-graphique "Passerelle API"
        Gateway[Passerelle API]
    fin

    sous-graphique "Microservices"
        UserSvc[Service utilisateur]
        OrderSvc[Service de commande]
        ProductSvc[Service produit]
        PaymentSvc[Service de paiement]
    fin

    sous-graphique "Couche de données"
        UserDB[(Base de données utilisateur)]
        OrderDB[(Base de données de commande)]
        ProductDB[(Base de données de produit)]
        Redis[(Cache Redis)]
    fin

    sous-graphique "Services externes"
        Stripe[Paiement Stripe]
        EmailAPI[API Email]
    fin

    MobileApp --> Gateway
    WebApp --> Gateway
    Gateway --> UserSvc
    Gateway --> OrderSvc
    Gateway --> ProductSvc
    Gateway --> PaymentSvc

    UserSvc --> UserDB
    UserSvc --> Redis
    OrderSvc --> OrderDB
    OrderSvc --> Redis
    ProductSvc --> ProductDB
    ProductSvc --> Redis

    PaymentSvc --> Stripe
    OrderSvc --> EmailAPI
    PaymentSvc --> EmailAPI

Exemple : Une architecture complète de microservices avec mise en cache, bases de données et dépendances externes

Exemple 2 : Flux d’authentification utilisateur (diagramme de séquence)

Les diagrammes de séquence sont parfaits pour documenter les interactions complexes entre les services.

sequenceDiagram
    numérotation automatique
    participant Utilisateur
    participant Frontend
    participant AuthSvc as Service d'authentification
    participant UserDB as Base de données utilisateur
    participant Cache as Cache Redis
    participant EmailSvc as Service d'envoi d'emails

    Utilisateur->>Frontend: Saisir les identifiants
    Frontend->>AuthSvc: POST /login (email, mot de passe)
    AuthSvc->>UserDB: Requête utilisateur par email
    UserDB-->>AuthSvc: Retourner le mot de passe haché et les données utilisateur
    AuthSvc->>AuthSvc: Vérifier le mot de passe avec bcrypt
    
    alt Identifiants valides
        AuthSvc->>AuthSvc: Générer un jeton JWT
        AuthSvc->>Cache: Stocker la session (clé: user_id, durée de vie: 1h)
        AuthSvc-->>Frontend: 200 OK + jeton JWT
        Frontend-->>Utilisateur: Redirection vers le tableau de bord
    else Identifiants invalides
        AuthSvc->>EmailSvc: Déclencher une alerte de connexion échouée
        AuthSvc-->>Frontend: 401 Non autorisé
        Frontend-->>Utilisateur: Afficher un message d'erreur
    fin
    
    Note au-dessus de AuthSvc,EmailSvc: Après 5 tentatives échouées, verrouiller le compte pendant 15 minutes

Exemple : Un flux d’authentification détaillé montrant les chemins de succès et d’échec, y compris les effets secondaires comme la mise en cache et les alertes

Exemple 3 : Infrastructure cloud sur AWS (diagramme de classes)

Les diagrammes de classes ne sont pas réservés au code ; ils peuvent modéliser les ressources cloud et leurs relations.

classDiagram
    class VPC {
        +string cidr_block
        +string region
        +createSubnet()
        +deleteSubnet()
    }

    class Sous-réseau {
        +string zone_de_disponibilité
        +string cidr_block
        +boolean est_public
        +attachRouteTable()
    }

    class InstanceEC2 {
        +string type_d_instance
        +string ami_id
        +int stockage_go
        +start()
        +stop()
        +reboot()
    }

    class BaseDeDonneesRDS {
        +string moteur
        +string version
        +int stockage_go
        +boolean multi_az
        +takeSnapshot()
        +restoreFromSnapshot()
    }

    class BucketS3 {
        +string nom_du_bucket
        +string region
        +boolean versioning_enabled
        +uploadFile()
        +downloadFile()
    }

    class RôleIAM {
        +string nom_du_rôle
        +string document_de_politique
        +attachPolicy()
        +detachPolicy()
    }

    VPC "1" --> "*" Sous-réseau
    Sous-réseau "1" --> "*" InstanceEC2
    Sous-réseau "1" --> "0..1" BaseDeDonneesRDS
    VPC "1" --> "0..*" BucketS3
    InstanceEC2 --> RôleIAM
    BaseDeDonneesRDS --> RôleIAM

Exemple : Modélisation de l’infrastructure AWS sous forme de classes avec des propriétés et des méthodes, utile pour la documentation et la planification de l’Infrastructure-as-Code

Exemple 4 : Traitement des commandes e-commerce (diagramme d’états)

Les diagrammes d’états excellent à montrer comment les entités transitent entre différents statuts.

stateDiagram-v2
    [*] --> Panier: L'utilisateur ajoute des articles
    Panier --> Paiement: L'utilisateur passe au paiement
    
    Paiement --> PaiementEnAttente: L'utilisateur soumet la commande
    PaiementEnAttente --> TraitementPaiement: Initialiser la passerelle de paiement
    
    TraitementPaiement --> Payé: Paiement réussi
    TraitementPaiement --> ÉchecPaiement: Paiement refusé
    
    ÉchecPaiement --> Paiement: L'utilisateur réessaie le paiement
    ÉchecPaiement --> [*]: L'utilisateur abandonne le panier
    
    Payé --> CommandeConfirmée: Envoyer un e-mail de confirmation
    CommandeConfirmée --> Préparation: Assigner à l'entrepôt
    
    Préparation --> Expédié: Remise au transporteur
    Expédié --> EnTransit: Le transporteur récupère
    
    EnTransit --> Livré: Livraison confirmée
    Livré --> DemandeAvis: Demander un avis à l'utilisateur
    
    DemandeAvis --> [*]: L'utilisateur soumet un avis
    Livré --> RemboursementDemandé: L'utilisateur initie un remboursement
    
    RemboursementDemandé --> RemboursementApprouvé: Le support approuve
    RemboursementApprouvé --> RemboursementTraitement: Argent remboursé
    RemboursementTraitement --> [*]: Commande clôturée
    
    state "Vérification de fraude à haut risque" as VérificationFraude {
        [*] --> VérifierScore
        VérifierScore --> FaibleRisque: Score < 50
        VérifierScore --> HautRisque: Score >= 50
        HautRisque --> RevueManuelle: Marquer pour l'équipe
        RevueManuelle --> FaibleRisque: Approuvé
        RevueManuelle --> ÉchecPaiement: Rejeté
    }
    
    PaiementEnAttente --> VérificationFraude: Évaluation des risques déclenchée
    VérificationFraude --> TraitementPaiement: FaibleRisque

Exemple : Machine d’états complète pour une commande e-commerce avec un état imbriqué de détection de fraude

Exemple 5 : Planification de sprint avec les problèmes GitHub (Graphique Git)

Les graphiques Git peuvent représenter des flux de travail au-delà de Git lui-même.

gitGraph
    commit id: "Planification de sprint" type: HIGHLIGHT
    
    branch sprint-1
    commit id: "Récit utilisateur #101 : Page de connexion"
    commit id: "Récit utilisateur #102 : Inscription utilisateur"
    
    branch bugfix/hotfix
    commit id: "Correctif urgent : Expiration du jeton d'authentification"
    checkout sprint-1
    merge bugfix/hotfix
    
    commit id: "Récit utilisateur #103 : Réinitialisation du mot de passe"
    
    checkout main
    merge sprint-1 tag: "v1.0.0"
    
    branch sprint-2
    commit id: "Fonctionnalité #201 : Panier d'achat"
    commit id: "Fonctionnalité #202 : Flux de paiement"
    
    branch experiment/ai-recommendations
    commit id: "POC : Moteur de recommandation ML"
    
    checkout sprint-2
    commit id: "Fonctionnalité #203 : Historique des commandes"
    
    checkout main
    merge sprint-2 tag: "v2.0.0"
    
    commit id: "Notes de version : Sprint 1 et 2 terminés"

Exemple : Visualisation de la gestion de projet, des sprints et des branches de fonctionnalités sous forme de graphique Git

La révolution de l’IA dans le diagrammage

Malgré l’élégance de Mermaid, la syntaxe peut constituer un obstacle. Qui veut déboguer une flèche mal alignée ou une parenthèse manquante lorsqu’on essaie de documenter un système ?

C’est ici que les outils alimentés par l’IA changent tout.

Correction automatique par IA

Des outils comme VPasCode (la plateforme Diagram as Code de Visual Paradigm) et Mermaid Chart ont intégré des modèles d’IA (comme Google Gemini et OpenAI) qui peuvent :

• Détecter automatiquement les erreurs de syntaxe

• Corriger les diagrammes cassés en un seul clic

• Suggérer des améliorations à la structure du diagramme

Voyons cela en action :

Code Mermaid cassé :

flowchart LR
    A[Frontend] --> B(API Gateway
    B --> C[Service Utilisateur]
    C --> D[(Base de données
    D --> E[Cache]

Code corrigé par l’IA :

flowchart LR
    A[Frontend] --> B(Passerelle API)
    B --> C(Service Utilisateur)
    C --> D[(Base de données)]
    D --> E[Mise en cache]

L’IA reconnaît les parenthèses et crochets de fermeture manquants et les corrige instantanément.

Langage naturel vers diagramme

Peut-être que la fonctionnalité la plus puissante est la génération de diagrammes à partir de descriptions en langage naturel. Avec des outils comme OpenDocs (la plateforme de documentation de VP), vous pouvez simplement décrire ce que vous voulez :

« Créez un organigramme montrant un utilisateur qui se connecte. Si les identifiants sont valides, redirigez vers le tableau de bord. Si invalides, affichez une erreur et autorisez 3 tentatives. Après 3 échecs, verrouillez le compte. »

Mermaid généré par l’IA :

flowchart TD
    Start([L'utilisateur tente de se connecter]) --> EnterCreds[Saisir l'email et le mot de passe]
    EnterCreds --> Validate{Valider les identifiants}
    Validate -->|Valide| Dashboard[Rediriger vers le tableau de bord]
    Validate -->|Invalide| CheckAttempts{Tentatives < 3}
    CheckAttempts -->|Oui| Increment[Incrémenter le compteur de tentatives]
    Increment --> ShowError[Afficher le message d'erreur]
    ShowError --> EnterCreds
    CheckAttempts -->|Non| LockAccount[Verrouiller le compte pendant 15 min]
    LockAccount --> SendAlert[Envoyer un e-mail d'alerte de sécurité]
    SendAlert --> End([Le processus se termine])
    Dashboard --> End

Traduction entre types de diagrammes

L’IA peut également traduire entre différents formats de diagrammes. Besoin de convertir un diagramme PlantUML en Mermaid ? Les outils d’IA peuvent le faire :

Entrée PlantUML :

@startuml
actor Utilisateur
participant "Frontend" as FE
participant "Backend" as BE
database "DB" as DB

Utilisateur -> FE: Cliquer sur Connexion
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: données utilisateur
BE --> FE: jeton JWT
FE --> Utilisateur: Afficher le tableau de bord
@enduml

Mermaid converti par l’IA :

sequenceDiagram
    actor Utilisateur
    participant Frontend
    participant Backend
    participant Base de données
    
    Utilisateur->>Frontend: Cliquer sur Connexion
    Frontend->>Backend: POST /login
    Backend->>Base de données: SELECT user
    Base de données-->>Backend: données utilisateur
    Backend-->>Frontend: jeton JWT
    Frontend-->>Utilisateur: Afficher le tableau de bord

Intégration de chatbot interactif

Certaines plateformes proposent désormais des interfaces de chatbot pour la création de diagrammes. Vous pouvez avoir une conversation :

Utilisateur : « Ajoutez un nouveau service appelé « Service d’inventaire » à mon diagramme d’architecture. »

IA : « Je vais ajouter un Service d’Inventaire connecté à vos services Produits et Commandes existants. »

Le diagramme se met à jour automatiquement

Utilisateur : « En fait, faites-le également se connecter à une nouvelle base de données appelée « InventoryDB ». »

IA : « Fait. Le Service d’Inventaire se connecte maintenant au Service Produits, au Service Commandes et à la nouvelle InventoryDB. »

Intégration du diagramme en code dans votre flux de travail

Étape 1 : Commencez petit

Ne tentez pas de diagrammer votre système entier d’un coup. Commencez par un seul composant—peut-être votre flux d’authentification ou une nouvelle fonctionnalité que vous développez.

Étape 2 : Intégrer dans la documentation

Gardez vos .mermaid fichiers à côté de votre documentation (par exemple, dans un /docs dossier). Utilisez des outils comme mermaid-cli pour les générer pendant le processus de construction.

Étape 3 : Exploitez le moteur unifié de VPasCode

Si vous travaillez dans une équipe avec des préférences diverses, VPasCode est inestimable. Il prend en charge plusieurs langages de diagramme en code au même endroit :

# Dans VPasCode, vous pouvez mélanger et assortir :
diagrams/
  ├── architecture.mermaid
  ├── deployment.puml      # PlantUML
  ├── database-erd.mermaid
  └── workflow.d2          # Langage D2

Étape 4 : Automatiser avec CI/CD

Ajoutez une étape à vos GitHub Actions ou GitLab CI :

- name: Générer les diagrammes Mermaid
  run: |
    for file in $(find docs -name "*.mermaid"); do
      npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
    done

- name: Télécharger vers le site de documentation
  run: |
    aws s3 sync docs/ s3://votre-bucket-docs/

Étape 5 : Examiner dans les Pull Requests

Établissez une politique selon laquelle toutes les modifications d’architecture nécessitent des mises à jour des diagrammes. Utilisez les commentaires de PR pour discuter des changements visuels :

Relecteur : « La mise en cache ne devrait-elle pas se situer entre le Service de Commandes et la Base de données ? Actuellement, elle n’est attachée qu’au Service Utilisateur. »

Auteur : « Bonne remarque. Je vais mettre à jour le diagramme. »

Impact en situation réelle : Une étude de cas

Imaginez une startup fintech ayant adopté le Diagramme en Code avec Mermaid et VPasCode :

• Avant : 47 fichiers Visio statiques, la plupart âgés de plus de 6 mois. Les nouveaux employés ont passé 3 semaines à comprendre l’architecture.

• Après : 12 diagrammes Mermaid, tous stockés dans Git, mis à jour à chaque fonctionnalité. Les nouveaux employés étaient productifs dès la première semaine.

Le CTO de l’équipe a noté : « Nous sommes passés de diagrammes servant de case à cocher pour la conformité à une partie vivante de notre processus de développement. Lorsque nous débattions d’une nouvelle architecture, nous ouvrons l’éditeur Mermaid et nous le dessinons littéralement en code. C’est un véritable changement de paradigme. »

L’avenir : Documentation continue

L’objectif ultime est la « documentation continue », où les diagrammes sont générés automatiquement à partir de votre infrastructure ou de votre code. Des outils émergent déjà capables de :

• Scanner vos manifests Kubernetes et générer des diagrammes de topologie de services

• Analyser les fichiers OpenAPI/Swagger et créer des diagrammes de flux d’API

• Surveiller vos ressources cloud et mettre à jour automatiquement les diagrammes d’architecture

Mermaid est au cœur de ce mouvement, offrant un format simple basé sur du texte que les machines peuvent générer et les humains peuvent comprendre.

Commencer dès aujourd’hui

Prêt à aller au-delà des images statiques ? Voici votre plan d’action :

1. Installez l’extension Mermaid dans votre IDE préféré (VS Code, IntelliJ)

2. Créez votre premier diagramme dans un .md fichier en utilisant la syntaxe de Mermaid

3. Découvrez l’offre gratuite de VPasCode pour découvrir le dessin de diagrammes assisté par IA

4. Créez un référentiel de documentation vivant à côté de votre base de code

5. Partagez cet article avec votre équipe et lancez la discussion

Votre architecture mérite mieux qu’un diagramme poussiéreux dans un dossier oublié. Il est temps de traiter vos diagrammes comme les actifs critiques qu’ils sont.