Mermaid Architect - Compétence de Diagrammes et Documentation H…

Mermaid Architect - Compétence de Diagrammes et Documentation Hiérarchiques

Système de diagrammes et de documentation Mermaid avec des guides spécialisés et des capacités de conversion de code en diagramme.

Table des matières

• Arbre de décision
• GitHub wiki, WikiTicket et Confluence
• Guides et ressources disponibles
• Modèles d'utilisation
• Flux de travail résilient
• Symboles sémantiques Unicode
• Utilitaires Python
• Exemples de l'arbre de décision
• Style à contraste élevé
• Organisation des fichiers
• Résumé du flux de travail
• Quand utiliser quoi
• Bonnes pratiques
• Parcours d'apprentissage

Arbre de décision

Comment fonctionne cette compétence :

1. L'utilisateur fait une demande → La compétence analyse l'intention
2. La compétence détermine le type de diagramme/document → Charge le(s) guide(s) approprié(s)
3. L'IA lit le guide spécialisé → Génère le diagramme/document à l'aide de modèles
4. Résultat livré → Avec validation et options d'exportation

Analyse de l'intention de l'utilisateur :

flowchart TD
    Start([Demande utilisateur]) --> Analyze{Analyser l'intention}

    Analyze -->|"workflow, processus, logique métier"| Activity[Charger le guide des diagrammes d'activité<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"infrastructure, déploiement, cloud"| Deploy[Charger le guide des diagrammes de déploiement<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"architecture système, composants"| Arch[Charger le guide d'architecture<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"flux API, interactions"| Sequence[Charger le guide des diagrammes de séquence<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"classe, ER, état, wiki, procédure"| WikiGuide[Charger le guide WikiTicket GitHub<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"code vers diagramme"| CodeToDiag[Charger le guide Code-vers-Diagramme<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"document de conception, docs complètes"| DesignDoc[Charger le modèle de document de conception<br/>assets/*-design-template.md]
    Analyze -->|"symboles unicode, icônes"| Unicode[Charger le guide des symboles Unicode<br/>references/guides/unicode-symboles/guide.md]
    Analyze -->|"extraire, valider, convertir"| Scripts[Utiliser les scripts Python<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[Générer le diagramme]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[Exécuter le script]

    Generate --> Validate{Valider ?}
    Validate -->|Oui| RunValidation[Exécuter la validation mmdc]
    Validate -->|Non| Output
    RunValidation --> Output[Produire le résultat]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

Guides et ressources disponibles

Guides par type de diagramme (references/guides/diagrams/)

Guide	Chemin complet	Charger lorsque l'utilisateur souhaite	Exemples
Diagrammes d'activité	references/guides/diagrams/activity-diagrams.md	Workflows, processus, logique métier, flux utilisateur, arbres de décision	"Afficher le flux de paiement", "Documenter le pipeline ETL", "Créer un workflow d'approbation"
Diagrammes de déploiement	references/guides/diagrams/deployment-diagrams.md	Infrastructure, architecture cloud, K8s, serverless, topologie réseau	"Afficher l'architecture AWS", "Documenter le déploiement GCP", "Créer un diagramme K8s"
Diagrammes d'architecture	references/guides/diagrams/architecture-diagrams.md	Architecture système, conception de composants, structure haut niveau	"Afficher les composants système", "Documenter les microservices", "Vue d'ensemble de l'architecture"
Diagrammes de séquence	references/guides/diagrams/sequence-diagrams.md	Interactions API, communication entre services, flux requête/réponse	"Afficher la séquence d'appels API", "Documenter le flux d'authentification", "Interactions entre services"
WikiTicket / GitHub / Confluence	references/guides/wiki-ticket-and-github.md	Documents de conception, procédures, exigences, publication wiki, images Confluence	"doc architecture", "procédure de code", "wiki", "Confluence"

Par défaut pour WikiTicket et GitHub wiki, cette compétence inclut classDiagram, erDiagram et stateDiagram-v2. Ne les envoyez pas à PlantUML. Si GitHub ne parvient pas à afficher C4 / architecture-beta / block-beta, passez à flowchart TD.

Guide Code-vers-Diagramme et exemples

Ressource	Chemin complet	Ce qu'elle fournit
Guide principal	references/guides/code-to-diagram/README.md	Workflow complet pour analyser n'importe quelle base de code et extraire des diagrammes
Spring Boot	examples/spring-boot/README.md	Architecture Contrôleur→Service→Repository, configuration de déploiement, séquence à partir de méthodes, activité à partir de logique métier
FastAPI	examples/fastapi/README.md	Modèles asynchrones Python, modèles Pydantic, injection de dépendances, déploiement cloud
React	examples/react/README.md	Hiérarchie de composants, gestion d'état, flux de données, pipeline de build
Python ETL	examples/python-etl/README.md	Pipeline de données, étapes de transformation, gestion d'erreurs, ordonnancement
Node/Express	examples/node-webapp/README.md	Chaîne de middleware, gestionnaires de routes, motifs asynchrones, déploiement
Application Web Java	examples/java-webapp/README.md	MVC traditionnel, conteneurs de servlets, déploiement WAR

Modèles de documents de conception

Modèle	Chemin complet	Utiliser pour	Charger lorsque
Conception d'architecture	assets/architecture-design-template.md	Architecture globale du système	"Créer un doc d'architecture", "Documenter la conception système"
Conception d'API	assets/api-design-template.md	Spécifications d'API	"Doc de conception d'API", "Documenter l'API REST"
Conception de fonctionnalité	assets/feature-design-template.md	Planification de fonctionnalité	"Conception de fonctionnalité", "Planifier une nouvelle fonctionnalité"
Conception de base de données	assets/database-design-template.md	Schéma de base de données	"Conception de base de données", "Documenter le schéma"
Conception système	assets/system-design-template.md	Système complet	"Doc de conception système", "Documentation complète du système"

Guide des symboles Unicode

Chemin complet : references/guides/unicode-symbols/guide.md

Charger lorsque l'utilisateur mentionne : "symboles unicode", "emoji dans les diagrammes", "icônes sémantiques", "ajouter des symboles"

Référence rapide :

• 📦 Infrastructure : ☁️ 🌐 🔌 📡 🗄️
• ⚙️ Calcul : ⚙️ ⚡ 🔄 ♻️ 🚀 💨
• 💾 Données : 💾 📦 📊 📈 🗃️ 🧊
• 📨 Messagerie : 📨 📬 📤 📥 🐰 📢
• 🔐 Sécurité : 🔐 🔑 🛡️ 🚪 👤 🎫
• 📝 Surveillance : 📝 📊 🚨 ⚠️ ✅ ❌

Scripts Python (scripts/)

Script	Utiliser pour	Charger lorsque
extract_mermaid.py	Extraire des diagrammes à partir de Markdown, valider la syntaxe, remplacer par des images	"extraire des diagrammes", "valider mermaid", "trouver tous les diagrammes"
mermaid_to_image.py	Convertir .mmd en PNG/SVG, conversion par lots, thèmes personnalisés	"convertir en image", "rendre un diagramme", "créer PNG"
resilient_diagram.py	Workflow complet : sauvegarder .mmd, générer l'image, valider, récupération d'erreur	"générer un diagramme", "créer un diagramme avec validation", "diagramme résilient"

GitHub wiki, WikiTicket et Confluence

Chargez references/guides/wiki-ticket-and-github.md pour les documents de conception WikiTicket, les procédures de code, les exigences, GitHub wiki ou Confluence.

Cible	Ce qu'il faut livrer
GitHub wiki / GFM	Bloc de code mermaid délimité. GitHub affiche class, ER, state, sequence, flowchart, C4.
Confluence / Notion / Word / PDF	Rendre également en PNG ou SVG (scripts/resilient_diagram.py ou mmdc) et télécharger l'image. Ne pas compter sur Confluence pour afficher Mermaid.

PlantUML est optionnel pour les maquettes Salt, les cas d'utilisation, le timing, ArchiMate, nwdiag et WBS. Ceux-ci sont toujours livrés en PNG ou SVG.

Modèles d'utilisation

Modèles de demandes courants et sélection de guides. Voir Quand utiliser quoi pour une cartographie complète.

Modèle	Exemple de demande	Guides à charger
Diagramme unique	"Crée un diagramme d'activité pour le flux de connexion"	Guide du type de diagramme + Symboles Unicode
Code vers diagramme	"Génère un déploiement à partir de application.yml"	Exemple de framework + Guide de déploiement
Document de conception	"Crée un document de conception d'API"	Modèle depuis assets/ + Guides de diagrammes pertinents
Extraire/Valider	"Extrais les diagrammes de design.md"	Utiliser scripts/extract_mermaid.py
Conversion par lots	"Convertir tous les .mmd en PNG"	Utiliser scripts/mermaid_to_image.py

Flux de travail résilient

CRITIQUE : Il s'agit de l'approche recommandée pour TOUTE génération de diagramme. Elle garantit la validation, la récupération d'erreur et une organisation cohérente des fichiers.

Guide complet : references/guides/resilient-workflow.md

Aperçu du flux de travail

flowchart LR
    A[1. Identifier le type] --> B[2. Sauvegarder .mmd + Image]
    B --> C{3. Valide ?}
    C -->|Oui| D[4. Ajouter au Markdown]
    C -->|Non| E[5. Récupération d'erreur]
    E --> F{Correctif trouvé ?}
    F -->|Oui| A
    F -->|Non| G[Recherche externe]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

Principe clé

N'ajoutez JAMAIS un diagramme au markdown tant qu'il n'a pas passé la validation. Cela évite les diagrammes cassés dans la documentation.

Utilisation du script (Recommandé)

# Générer avec récupération d'erreur complète
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

Sortie : Fichiers .mmd et .png dans le répertoire ./diagrams/.

Convention de nommage des fichiers

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

Exemple : ./diagrams/api_design_01_sequence_auth_flow.png

Priorité de récupération d'erreur

Lorsque la validation échoue, le flux de travail exécute automatiquement :

1. Vérifier le guide de dépannage - references/guides/troubleshooting.md (28 erreurs documentées)
2. Recherche avec perplexity - perplexity_ask MCP pour les questions de syntaxe
3. Recherche avec brave - brave_web_search MCP pour les solutions récentes
4. Demander à gemini - Compétence gemini pour une perspective alternative
5. Recherche générale - Outil WebSearch comme solution de repli

Étapes de repli manuelles

Si le script n'est pas disponible :

1. Identifier le type de diagramme à partir de la première ligne (flowchart, sequence, etc.)
2. Charger le guide de référence depuis references/guides/diagrams/
3. Sauvegarder dans ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
4. Valider : mmdc -i file.mmd -o file.png -b transparent
5. En cas d'erreur : Rechercher dans references/guides/troubleshooting.md l'erreur correspondante
6. Si non trouvée : Utiliser les outils de recherche dans l'ordre de priorité ci-dessus
7. Ajouter la référence : ![Description](./diagrams/filename.png)

Modèle 6 : Génération de diagramme résiliente

Utilisateur : "Crée un diagramme de séquence et ajoute-le au document de conception"

Actions de la compétence :

1. Identifier l'intention : génération de diagramme + intégration dans markdown
2. Charger le guide de flux de travail : references/guides/resilient-workflow.md
3. Identifier le type de diagramme : séquence
4. Charger le guide de diagramme : references/guides/diagrams/sequence-diagrams.md
5. Générer le code Mermaid à l'aide des modèles
6. Exécuter le flux de travail résilient :

   python scripts/resilient_diagram.py \
       --code "[code généré]" \
       --markdown-file design_doc \
       --diagram-num 1 \
       --title "api_sequence" \
       --json
   

7. Si la validation échoue → Appliquer le correctif de dépannage → Réessayer
8. En cas de succès → Ajouter ![API Sequence](./diagrams/design_doc_01_sequence_api_sequence.png) au markdown

Symboles sémantiques Unicode

Utilisez toujours des symboles Unicode pour améliorer la clarté des diagrammes. Modèles courants :

Infrastructure et déploiement

graph TB
    Client[👤 Utilisateur] --> LB[🌐 Équilibreur de charge]
    LB --> App1[⚙️ Serveur d'application 1]
    LB --> App2[⚙️ Serveur d'application 2]
    App1 --> DB[(💾 Base de données)]
    App1 --> Cache[(⚡ Redis)]

Flux d'activité avec états

flowchart TD
    Start([🚀 Démarrer]) --> Process[⚙️ Traiter les données]
    Process --> Check{✓ Valide ?}
    Check -->|Oui| Save[💾 Sauvegarder]
    Check -->|Non| Error[❌ Erreur]
    Save --> Complete([✅ Terminé])

Architecture microservices

graph TB
    API[🌐 API Gateway] --> Auth[🔐 Service d'authentification]
    API --> Orders[📋 Service de commandes]
    Orders --> Queue[📬 File de messages]
    Queue --> Worker[⚙️ Travailleur en arrière-plan]
    Worker --> Storage[📦 Stockage d'objets]

Pour la référence complète des symboles, charger : references/guides/unicode-symbols/guide.md

Utilitaires Python

Extraire les diagrammes Mermaid

# Lister tous les diagrammes
python scripts/extract_mermaid.py document.md --list-only

# Extraire dans des fichiers séparés
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Valider tous les diagrammes
python scripts/extract_mermaid.py document.md --validate

# Remplacer par des références d'images (pour téléchargement Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Convertir en images

# Conversion unique
python scripts/mermaid_to_image.py diagram.mmd output.png

# Avec paramètres personnalisés
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Conversion par lots d'un répertoire
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# Depuis stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Flux de travail résilient (Recommandé)

# Avec récupération d'erreur et validation
python scripts/resilient_diagram.py \
    --code "sequenceDiagram; A->>B: Hello" \
    --markdown-file api_doc \
    --diagram-num 1 \
    --title "greeting" \
    --format png

# Sortie complète en JSON
python scripts/resilient_diagram.py \
    --code "flowchart LR; A-->B" \
    --markdown-file design \
    --diagram-num 1 \
    --title "simple_flow" \
    --json

Exemples de l'arbre de décision

Exemple 1 : Demande de diagramme simple

Utilisateur : "Crée un diagramme de séquence pour l'authentification"

Actions de la compétence :

1. Charger : references/guides/diagrams/sequence-diagrams.md
2. Charger : references/guides/unicode-symbols/guide.md
3. Générer le diagramme
4. Valider et ajouter au markdown

Exemple 2 : Demande de document de conception

Utilisateur : "Crée un document de conception de fonctionnalité incluant un diagramme d'architecture"

Actions de la compétence :

1. Charger : assets/feature-design-template.md
2. Charger : references/guides/diagrams/architecture-diagrams.md
3. Générer le document avec le diagramme intégré

Exemple 3 : Code vers diagramme

Utilisateur : "Génère un diagramme de déploiement pour mon application Spring Boot"

Actions de la compétence :

1. Charger : examples/spring-boot/README.md
2. Charger : references/guides/diagrams/deployment-diagrams.md
3. Analyser application.yml
4. Générer et valider le diagramme de déploiement

Exemple 4 : Demande de validation

Utilisateur : "Valide tous les diagrammes dans le wiki"

Actions de la compétence :

1. Exécuter : python scripts/extract_mermaid.py wiki.md --validate
2. Rapporter les diagrammes valides et ceux en échec
3. Pour les échecs : exécuter le flux de récupération
4. Mettre à jour le wiki avec les diagrammes corrigés

Style à contraste élevé

Diagramme de séquence

sequenceDiagram
    participant User as 👤 Utilisateur
    participant Auth as 🔐 Service d'authentification
    participant DB as 💾 Base de données

    User->>Auth: 🔑 Demander une connexion
    Auth->>DB: 🔍 Vérifier les identifiants
    DB-->>Auth: ✅ Identifiants valides
    Auth-->>User: 🔓 Connexion réussie

Diagramme d'architecture

graph TB
    subgraph Client
        Browser[🌐 Navigateur]
    end
    
    subgraph Frontend
        React[⚛️ React App]
        State[🔵 État global]
    end
    
    subgraph Backend
        API[📡 API Gateway]
        Services[⚙️ Microservices]
    end
    
    Browser --> React
    React --> State
    State --> API
    API --> Services

Organisation des fichiers

.
├── assets/
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── feature-design-template.md
│   ├── database-design-template.md
│   └── system-design-template.md
├── examples/
│   ├── spring-boot/
│   │   └── README.md
│   ├── fastapi/
│   │   └── README.md
│   ├── react/
│   │   └── README.md
│   ├── python-etl/
│   │   └── README.md
│   ├── node-webapp/
│   │   └── README.md
│   └── java-webapp/
│       └── README.md
├── references/
│   ├── guides/
│   │   ├── code-to-diagram/
│   │   │   └── README.md
│   │   ├── diagrams/
│   │   │   ├── activity-diagrams.md
│   │   │   ├── architecture-diagrams.md
│   │   │   ├── deployment-diagrams.md
│   │   │   └── sequence-diagrams.md
│   │   ├── unicode-symbols/
│   │   │   └── guide.md
│   │   ├── resilient-workflow.md
│   │   ├── troubleshooting.md
│   │   └── wiki-ticket-and-github.md
│   └── README.md
└── scripts/
    ├── extract_mermaid.py
    ├── mermaid_to_image.py
    └── resilient_diagram.py

Résumé du flux de travail

Flux de base

1. Recevoir la demande - Analyser le type de diagramme/document
2. Charger les ressources - Guide approprié + modèles + symboles
3. Générer - Créer le diagramme à l'aide de Mermaid
4. Valider - Utiliser mmdc ou le script de validation
5. Sauvegarder - .mmd + PNG/SVG dans ./diagrams/
6. Intégrer - Ajouter au document Markdown

Flux avec récupération

1. Échec de validation - Identifier l'erreur
2. Guide de dépannage - Vérifier les solutions connues
3. Recherche externe - Utiliser les MCP pour trouver des correctifs
4. Nouvelle tentative - Corriger et valider à nouveau
5. Succès - Continuer vers la sauvegarde et l'intégration

Quand utiliser quoi

Intention utilisateur	Premier guide à charger	Ressources secondaires
Workflow / Processus	diagrams/activity-diagrams.md	Symboles Unicode
Infrastructure / Cloud	diagrams/deployment-diagrams.md	Guide de flux de travail résilient
Architecture système	diagrams/architecture-diagrams.md	Modèle de conception
Flux API	diagrams/sequence-diagrams.md	Exemple de framework
Documentation	wiki-ticket-and-github.md	Modèles de conception
Conversion code	code-to-diagram/README.md	Exemple de framework
Extraction/Validation	Scripts Python	Guide de dépannage
Icônes personnalisées	unicode-symbols/guide.md	Documentation Mermaid

Bonnes pratiques

Validation des diagrammes

• Toujours valider les diagrammes avant de les inclure dans la documentation
• Utiliser le flux de travail résilient pour la récupération d'erreur
• Conserver les fichiers .mmd et .png dans ./diagrams/

Gestion des erreurs

• Vérifier d'abord references/guides/troubleshooting.md
• Utiliser les outils de recherche dans l'ordre de priorité
• Ne jamais laisser un diagramme non valide dans le markdown

Style des diagrammes

• Utiliser des symboles Unicode pour améliorer la clarté
• Maintenir des couleurs cohérentes dans les diagrammes liés
• Utiliser le style à contraste élevé pour une meilleure lisibilité
• Documenter les diagrammes complexes avec des sous-graphes

Organisation des fichiers

• Stocker toutes les sorties de diagrammes dans ./diagrams/
• Utiliser le format de nommage : <fichier>_<num>_<type>_<titre>
• Commiter les fichiers .mmd et .png pour les intégrer dans les workflows CI/CD

Parcours d'apprentissage

Débutant

1. Commencer par des diagrammes d'activité et de séquence simples
2. Utiliser les modèles de conception de base
3. Apprendre la syntaxe Mermaid de base

Intermédiaire

1. Maîtriser le code-vers-diagramme avec les exemples de frameworks
2. Configurer des diagrammes C4 et d'architecture
3. Utiliser des symboles Unicode et des styles personnalisés

Avancé

1. Écrire des workflows de validation et conversion par lots
2. Intégrer dans les pipelines CI/CD
3. Créer des modèles de diagramme personnalisés
4. Débuguer la syntaxe Mermaid complexe à l'aide du guide de dépannage

---

Cette compétence fournit des capacités complètes de diagrammes et de documentation Mermaid. Pour des guides détaillés sur des types de diagrammes spécifiques ou des workflows, chargez les ressources appropriées depuis les répertoires references/ ou examples/.