Chapitre 13 : Documentation d'Architecture

Introduction

La documentation d'architecture est essentielle pour la communication, la maintenance et l'évolution des systèmes. Ce chapitre explore les approches modernes de documentation : Documentation as Code, C4 Model, ADR, RFCs, OpenAPI, AsyncAPI et ArchiMate.

---

13.1 Documentation as Code

13.1.1 Principe

La Documentation as Code (Docs as Code) est une approche qui applique les principes du développement logiciel à la documentation :

Diagramme en cours de génération...

Principes :

• Stockée dans le repository (docs/)
• Versionnée avec Git
• Revue via Pull Requests
• Générée et publiée automatiquement (CI/CD)
• Écrite en markdown/AsciiDoc
• Diagrams as Code (Mermaid, PlantUML)

13.1.2 Outils de Documentation as Code

13.1.3 Architecture du dossier docs/

docs/
├── architecture/
│   ├── context.md          # C4 Contexte
│   ├── containers.md       # C4 Conteneurs
│   ├── components/         # C4 Composants
│   │   ├── commandes.md
│   │   └── paiement.md
│   ├── decisions/          # ADR
│   │   ├── adr-001.md
│   │   └── adr-002.md
│   └── diagrams/           # Diagrams as Code
│       ├── architecture.puml
│       └── flows.puml
├── api/
│   ├── openapi.yaml
│   └── asyncapi.yaml
├── guides/
│   ├── getting-started.md
│   └── deployment.md
└── README.md

---

13.2 C4 Model pour la documentation

13.2.1 Les 4 niveaux

Diagramme en cours de génération...

13.2.2 Documentation C4 avec Structurizr

Structurizr permet de définir l'architecture en code (DSL) :

workspace {
    model {
        user = person "Client" "Utilisateur du système"
        system = softwareSystem "SaaS E-commerce" "Plateforme de vente en ligne"
        
        user -> system "Utilise"
    }
    
    views {
        systemContext system "Contexte" {
            include *
            autoLayout
        }
    }
}

13.2.3 Exemple C4 Container diagram (Mermaid)

Diagramme en cours de génération...

---

13.3 ADR pour les décisions

Les ADR (ch. 12) font partie intégrante de la documentation d'architecture :

docs/architecture/decisions/
├── 001-architecture-microservices.md
├── 002-choix-base-donnees.md
└── index.md

Bonnes pratiques :

• Toujours lier les ADR aux diagrammes C4 concernés
• Utiliser les ADR pour documenter le "pourquoi" des choix C4
• Maintenir l'index ADR à jour

---

13.4 RFCs pour les propositions

13.4.1 Qu'est-ce qu'une RFC ?

Une RFC (Request For Comments) est un document de proposition technique qui suit un processus structuré d'examen par les pairs, popularisé par l'équipe React (et avant elle, l'IETF).

13.4.2 Structure d'une RFC

# RFC NNN : Titre

## Résumé
Description en 2-3 phrases du problème et de la solution proposée.

## Motivation
Pourquoi ce changement est-il nécessaire ?

## Design détaillé
Description technique de l'implémentation.

## Alternatives considérées
Quelles autres options ont été explorées ?

## Questions ouvertes
Points qui nécessitent encore des discussions.

13.4.3 Cycle de vie d'une RFC

Diagramme en cours de génération...

---

13.5 OpenAPI pour les APIs REST

13.5.1 Présentation

OpenAPI (ex Swagger) est le standard de facto pour documenter les APIs REST.

openapi: 3.1.0
info:
  title: API Commandes
  version: 1.0.0
  description: API de gestion des commandes

paths:
  /commandes:
    get:
      summary: Liste des commandes
      parameters:
        - name: clientId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Liste des commandes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Commande'
    
    post:
      summary: Créer une commande
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreerCommande'
      responses:
        '201':
          description: Commande créée

components:
  schemas:
    Commande:
      type: object
      properties:
        id:
          type: string
        clientId:
          type: string
        montant:
          type: number
        statut:
          type: string
    CreerCommande:
      type: object
      required:
        - clientId
        - articles
      properties:
        clientId:
          type: string
        articles:
          type: array
          items:
            type: object
            properties:
              produitId:
                type: string
              quantite:
                type: integer

13.5.2 Outils OpenAPI

---

13.6 AsyncAPI pour les APIs événementielles

13.6.1 Présentation

AsyncAPI est l'équivalent d'OpenAPI pour les APIs événementielles (Kafka, RabbitMQ, MQTT).

asyncapi: 2.6.0
info:
  title: Event Bus Commandes
  version: 1.0.0

channels:
  commande.creee:
    publish:
      message:
        name: CommandeCréée
        payload:
          type: object
          properties:
            commandeId:
              type: string
            clientId:
              type: string
            montant:
              type: number
      
  commande.confirmee:
    publish:
      message:
        name: CommandeConfirmée
        payload:
          type: object
          properties:
            commandeId:
              type: string
            dateConfirmation:
              type: string
              format: date-time

servers:
  production:
    url: kafka://kafka-cluster:9092
    protocol: kafka

13.6.2 Architecture événementielle documentée

Diagramme en cours de génération...

---

13.7 ArchiMate pour l'architecture enterprise

13.7.1 Couches ArchiMate

Diagramme en cours de génération...

13.7.2 Exemple de diagramme ArchiMate

Diagramme en cours de génération...

---

13.8 Structurer un wiki d'architecture

13.8.1 Structure recommandée

📁 Wiki d'Architecture
├── 🏠 Accueil
│   ├── Vue d'ensemble du système
│   ├── Glossaire
│   └── Principes d'architecture
├── 📐 Architecture
│   ├── C1 — Contexte
│   ├── C2 — Conteneurs
│   ├── C3 — Composants
│   └── Décisions (ADR)
├── 🔌 APIs
│   ├── API REST (OpenAPI)
│   ├── API Événementielle (AsyncAPI)
│   └── Contrats de service
├── 🏗️ Infrastructure
│   ├── Diagramme de déploiement
│   ├── Réseau et sécurité
│   └── DRP / Backup
├── 📊 Qualité
│   ├── Performance et scalabilité
│   ├── Sécurité
│   └── Monitoring
├── 🔄 Processus
│   ├── CI/CD
│   ├── Revue de code
│   └── Gestion des incidents
└── 📚 Références
    ├── Glossaire technique
    ├── Bibliographie
    └── Conventions

13.8.2 Bonnes pratiques

---

13.9 Synthèse : Choisir le bon outil

Diagramme en cours de génération...

---

Références

• Simon Brown — Software Architecture for Developers (C4 Model)
• OpenAPI Initiative — openapis.org
• AsyncAPI Initiative — asyncapi.com
• The Open Group — ArchiMate Specification
• Structurizr — structurizr.com
• Docusaurus — docusaurus.io
• MkDocs — mkdocs.org