Modélisation¶

Communiquer une architecture avant de l'écrire — les diagrammes comme outil de pensee et de validation.

Pourquoi modéliser¶

Un diagramme n'est pas une documentation après coup. C'est un outil de réflexion : dessiner un système révélé ses incohérences avant qu'elles deviennent du code.

Trois raisons de modéliser :

1. Communication : aligner l'équipe sur une vision partagee en 10 minutes plutôt qu'en 10 jours de code
2. Validation : détecter les problèmes de conception (cycles, couplage excessif) avant qu'ils soient coûteux
3. Documentation vivante : un diagramme as code est versionne avec le code et reste à jour

UML — les trois diagrammes utiles¶

UML contient 14 types de diagrammes. Dans la pratique quotidienne, trois couvrent 90% des besoins.

Diagramme de classes¶

Pour modéliser les entités et leurs relations :

classDiagram
    class Order {
        +String id
        +String status
        +add_item(product, qty)
        +total() float
        +confirm()
    }
    class OrderItem {
        +String product_id
        +int quantity
        +float unit_price
        +subtotal() float
    }
    class Customer {
        +String id
        +String email
    }
    Order "1" --> "*" OrderItem : contient
    Order "*" --> "1" Customer : appartient a

Quand l'utiliser : explorer un modèle de domaine, documenter les entités clés, onboarder un nouveau développeur.

Diagramme de sequence¶

Pour modéliser les interactions entre composants dans le temps :

sequenceDiagram
    participant Client
    participant API
    participant UseCase
    participant Repository
    participant DB

    Client->>API: POST /orders
    API->>UseCase: create_order(command)
    UseCase->>Repository: find_customer(id)
    Repository->>DB: SELECT ...
    DB-->>Repository: customer row
    Repository-->>UseCase: Customer
    UseCase->>Repository: save(order)
    Repository->>DB: INSERT ...
    DB-->>Repository: ok
    UseCase-->>API: OrderCreated
    API-->>Client: 201 Created

Quand l'utiliser : debugger un flux complexe, désigner un protocole, expliquer une intégration avec un tiers.

Diagramme d'activité¶

Pour modéliser un processus métier ou un algorithme :

flowchart TD
    A([Commande recue]) --> B{Stock disponible ?}
    B -- Oui --> C[Reserver stock]
    B -- Non --> D[Notifier rupture]
    D --> E([Fin])
    C --> F{Paiement valide ?}
    F -- Non --> G[Liberer stock]
    G --> H[Notifier echec]
    H --> E
    F -- Oui --> I[Confirmer commande]
    I --> J[Envoyer email]
    J --> E

Quand l'utiliser : clarifier une règle métier avec un product owner, documenter un workflow d'approbation.

C4 Model¶

Le C4 Model (Simon Brown) propose quatre niveaux de zoom pour décrire un système logiciel.

graph TD
    subgraph L1["Niveau 1 — Contexte (zoom out)"]
        U1["Utilisateur"] --> S["Systeme"]
        S --> EXT["Systeme externe"]
    end
    subgraph L2["Niveau 2 — Conteneurs"]
        WEB["Web App"] --> API2["API Backend"]
        API2 --> DB2["Base de donnees"]
    end
    subgraph L3["Niveau 3 — Composants"]
        CTRL["OrderController"] --> UC2["CreateOrderUseCase"]
        UC2 --> REPO["OrderRepository"]
    end

Diagrammes as code¶

Les diagrammes dans des fichiers image (PNG, Visio) vieillissent mal et ne se versionnent pas. Les diagrammes as code vivent dans le dépôt git.

Mermaid (recommande pour MkDocs)¶

```mermaid
sequenceDiagram
    A->>B: message
    B-->>A: réponse

Supporte nativement par GitHub, GitLab et MkDocs Material. Syntaxe simple, rendu correct.

### PlantUML

```plantuml
@startuml
class Order {
  +confirm()
}
@enduml

Plus expressif que Mermaid pour l'UML complet, mais nécessité un serveur de rendu ou un plugin.

Structurizr DSL (pour C4)¶

workspace {
    model {
        user = person "Utilisateur"
        system = softwareSystem "E-commerce" {
            api = container "API" "FastAPI"
            db = container "Database" "PostgreSQL"
        }
        user -> api "utilise"
        api -> db "lit/ecrit"
    }
}

Quel diagramme pour quel besoin¶