Diagrammes as code¶

Mermaid, PlantUML et le modèle C4 — produire des diagrammes versionnables, reviewables et toujours à jour.

Pourquoi des diagrammes as code ?¶

Un diagramme dans un fichier .png ou .pptx :

• Se desynchonise du code sans que personne ne s'en apercoit
• Ne peut pas être revu en diff dans une pull request
• Se perd dans un dossier partagé ou une confluence oubliee

Un diagramme as code :

• Est versionne avec le code qu'il documente
• Évolue dans les mêmes pull requests
• Est généré automatiquement à chaque build

Mermaid¶

Mermaid est le standard de facto pour les diagrammes dans la documentation Markdown. Il est supporte nativement par GitHub, GitLab, MkDocs Material, et Notion.

Flowchart¶

graph TD
    A[Requete HTTP] --> B{Token valide ?}
    B -- Oui --> C[Traitement]
    B -- Non --> D[401 Unauthorized]
    C --> E{Role suffisant ?}
    E -- Oui --> F[Reponse 200]
    E -- Non --> G[403 Forbidden]

Code source :

graph TD
    A[Requete HTTP] --> B{Token valide ?}
    B -- Oui --> C[Traitement]
    B -- Non --> D[401 Unauthorized]
    C --> E{Role suffisant ?}
    E -- Oui --> F[Reponse 200]
    E -- Non --> G[403 Forbidden]

Diagramme de sequence¶

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant User Service

    Client->>API Gateway: POST /login
    API Gateway->>Auth Service: Valider credentials
    Auth Service->>User Service: Recuperer profil
    User Service-->>Auth Service: Profil utilisateur
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK + token

Diagramme de classes¶

classDiagram
    class Order {
        +String id
        +User customer
        +List~OrderLine~ lines
        +OrderStatus status
        +total() float
        +cancel() void
    }
    class OrderLine {
        +Product product
        +int quantity
        +float unitPrice
        +subtotal() float
    }
    class Product {
        +String sku
        +String name
        +float price
    }
    Order "1" --> "1..*" OrderLine
    OrderLine "1" --> "1" Product

Diagramme ER¶

erDiagram
    USER {
        uuid id PK
        string email UK
        string name
        timestamp created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        string status
        float total
        timestamp created_at
    }
    ORDER_LINE {
        uuid id PK
        uuid order_id FK
        string product_sku
        int quantity
        float unit_price
    }
    USER ||--o{ ORDER : "passe"
    ORDER ||--|{ ORDER_LINE : "contient"

Le modèle C4¶

Le modèle C4 (Context, Container, Component, Code) structure les diagrammes d'architecture en quatre niveaux de zoom.

graph TB
    subgraph "Niveau 1 - Contexte"
        direction TB
        U[Utilisateur] --> S[Systeme]
        S --> E[Systeme externe]
    end

Niveau 1 : Contexte¶

Qui utilise le système et avec quoi il interagit.

graph TB
    Dev["Developpeur\n[Personne]"]
    User["Client final\n[Personne]"]
    Stripe["Stripe\n[Systeme externe]"]
    Email["SendGrid\n[Systeme externe]"]
    App["Plateforme e-commerce\n[Systeme logiciel]"]

    Dev --> App
    User --> App
    App --> Stripe
    App --> Email

Niveau 2 : Conteneurs¶

Les blocs deployables qui composent le système.

graph TB
    Browser["Navigateur\n[SPA React]"]
    API["API Backend\n[FastAPI / Python]"]
    DB[("PostgreSQL\n[Base de donnees]")]
    Cache[("Redis\n[Cache / Sessions]")]
    Queue["RabbitMQ\n[File de messages]"]
    Worker["Worker async\n[Celery]"]

    Browser -- "HTTPS / REST" --> API
    API -- "SQL" --> DB
    API -- "Redis protocol" --> Cache
    API -- "AMQP" --> Queue
    Queue --> Worker
    Worker -- "SQL" --> DB

Niveau 3 : Composants¶

Les modules internes d'un conteneur.

graph TB
    subgraph "API Backend"
        Router["Router FastAPI"]
        AuthMiddleware["Auth Middleware"]
        OrderController["Order Controller"]
        PaymentService["Payment Service"]
        NotificationService["Notification Service"]
    end

    Router --> AuthMiddleware
    AuthMiddleware --> OrderController
    OrderController --> PaymentService
    OrderController --> NotificationService

PlantUML¶

PlantUML offre plus de types de diagrammes que Mermaid (timing, deployment, BPMN) mais nécessité un rendu server-side ou un plugin.

@startuml
actor Utilisateur
participant "API Gateway" as API
participant "Auth Service" as Auth
database "Redis" as Cache

Utilisateur -> API : GET /resource
API -> Auth : Valider token
Auth -> Cache : Verifier session
Cache --> Auth : Session valide
Auth --> API : Autorise
API --> Utilisateur : 200 OK
@enduml

Tableau des types de diagrammes¶

Intégration dans MkDocs Material¶

# mkdocs.yml
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js

Les diagrammes Mermaid dans des blocs de code ```mermaid sont alors rendus automatiquement.

Bonnes pratiques¶

• Versionnez les sources, pas les images : committez le code Mermaid/PlantUML, pas les .png.
• Un diagramme par concept : evitez les mega-diagrammes illisibles. Decoupez par niveau C4.
• Titre explicite : chaque diagramme doit avoir un titre et une legende si nécessaire.
• Liens depuis l'ADR : quand un ADR implique une nouvelle architecture, liez le diagramme correspondant.

Prochaine étape¶

Avec les diagrammes, vous documentez l'architecture. Voyons maintenant comment documenter les API que vous exposez a vos consommateurs.

Documentation d'API →