Documenter une architecture : modèle C4 et diagramme de déploiement

Documenter une architecture, c'est produire les quelques schémas et textes qui permettent à quelqu'un qui ne connaît pas l'application de comprendre en quelques minutes de quoi elle est faite, où elle s'exécute et pourquoi elle a été construite ainsi. Le modèle C4 de Simon Brown propose quatre niveaux de zoom : contexte, conteneurs, composants, code. Le diagramme de déploiement UML montre sur quelles machines tourne chaque programme. Les ADR consignent les décisions. Ce chapitre les applique à ResaSalles, et c'est exactement ce qu'attend la commission de l'E6 dans ton dossier.

Pourquoi un schéma ne suffit pas toujours

Le schéma d'architecture typique d'un dossier d'étudiant est une boîte « Application » reliée à une boîte « Base de données ». Il est juste, mais il ne répond à aucune question utile : qui utilise l'application ? Quels programmes faut-il installer ? Où tournent-ils ? Comment communiquent-ils, et avec quel protocole ? À l'inverse, un schéma qui montre tout à la fois (utilisateurs, serveurs, classes, tables) est illisible.

Le modèle C4 règle ce problème par le zoom : chaque diagramme répond à une question, à un niveau de détail.

Les quatre niveaux du modèle C4

Niveau 1 : le diagramme de contexte

Le diagramme de contexte de ResaSalles tient en cinq éléments :

• Salarié (personne) : consulte les salles et réserve un créneau.
• Assistante de l'accueil (personne) : réserve pour les visiteurs, imprime les badges.
• ResaSalles (le système, au centre) : gère les salles et les réservations.
• Annuaire de l'entreprise (système externe, Active Directory) : authentifie les salariés.
• Serveur de messagerie (système externe) : envoie les confirmations et les rappels.

Sur chaque flèche, un verbe : « réserve une salle avec », « authentifie les utilisateurs auprès de », « envoie les e-mails par ». Aucune technologie à ce niveau : le directeur de Brévent Industrie doit pouvoir le lire.

Niveau 2 : le diagramme de conteneurs

C'est le diagramme le plus utile pour un dossier d'E6. Il ouvre la boîte « ResaSalles » et montre les programmes qui la composent.

Chaque boîte porte trois informations : un nom, une technologie et une responsabilité en une phrase. Chaque flèche porte une intention (« appelle », « lit et écrit ») et un protocole (« JSON/HTTPS », « SQL/TCP 3306 »). Une légende explique les formes et les couleurs. Ces règles simples rendent le schéma lisible sans commentaire oral.

Niveau 3 : le diagramme de composants

Il zoome dans un conteneur, en pratique l'API. On y retrouve les couches du chapitre 6 : les contrôleurs (ReservationController, SalleController), le middleware d'authentification, les services (ReservationService), les Repository, le client de messagerie. Ce diagramme est utile pour expliquer l'organisation du code à un nouveau développeur ; dans un dossier d'E6, une arborescence commentée des dossiers fait souvent le même travail en moins de place.

Niveau 4 : le code

Le niveau 4 n'est presque jamais dessiné à la main : un diagramme de classes UML ou un schéma relationnel, généré par l'environnement de développement ou par l'outil de gestion de base de données, suffit. Les diagrammes de classes et de séquence sont présentés dans le cours UML ; le schéma relationnel dans le cours Merise.

Le diagramme de déploiement

Le diagramme de conteneurs dit quoi ; le diagramme de déploiement dit où. C'est un diagramme UML qui représente les nœuds (machines physiques ou virtuelles, environnements d'exécution), les artefacts déployés dessus (fichiers, programmes) et les chemins de communication entre les nœuds.

En UML, un nœud se dessine comme un pavé (une boîte en trois dimensions), un artefact comme un rectangle marqué «artifact», et les chemins de communication comme des traits annotés du protocole. Dans un dossier d'E6, ce diagramme sert aussi de base à la discussion sur la sécurité : quels ports sont ouverts, entre quels réseaux (DMZ et segmentation).

Les décisions d'architecture : les ADR

Un schéma montre le résultat, pas les raisons. Six mois plus tard, personne ne se souvient pourquoi on a choisi une API plutôt qu'une connexion directe à MySQL. Un ADR (Architecture Decision Record, enregistrement de décision d'architecture) consigne chaque décision importante dans un court fichier texte, versionné avec le code (souvent dans docs/adr/).

# ADR 003 : l'application de l'accueil passe par l'API

Date : 2026-10-12
Statut : acceptée

## Contexte
L'application WinForms de l'accueil se connecte directement à MySQL. La chaîne de
connexion, avec son mot de passe, est présente sur les deux postes de l'accueil, et
le port 3306 est ouvert à tout le réseau des postes. Les règles de réservation sont
écrites deux fois : dans l'API et dans l'application de bureau.

## Décision
L'application de bureau appelle l'API REST en HTTPS, avec le même mécanisme
d'authentification que l'application web. Elle n'a plus d'accès direct à la base.

## Conséquences
+ Les règles ne sont plus écrites qu'une fois, dans l'API.
+ Le port 3306 n'est plus ouvert qu'au serveur de l'API.
- L'application de bureau ne fonctionne plus si l'API est indisponible.
- Il faut réécrire la couche d'accès aux données de l'application de bureau (environ 2 jours).

Un ADR ne se modifie pas après coup : si la décision change, on écrit un nouvel ADR qui remplace l'ancien, et on change le statut de l'ancien. L'historique des raisons reste lisible.

Le README, porte d'entrée du dépôt

Le fichier README.md à la racine du dépôt est le premier document que lit la commission ou un développeur. Pour un projet d'E6, il contient au minimum :

1. une description de l'application en trois lignes ;
2. le schéma de conteneurs (ou un lien vers docs/architecture.md) ;
3. les prérequis (versions de Node.js, .NET, MySQL) ;
4. l'installation et le lancement en quelques commandes, base de test comprise ;
5. le lancement des tests ;
6. l'organisation des dossiers, en une arborescence commentée.

Les outils

Les outils « diagramme sous forme de texte » ont un grand avantage pour un projet : le schéma vit dans le dépôt Git, à côté du code, et se met à jour dans le même commit.

Exercices

# ADR 004 : interface des salariés en SPA React

Date : 2026-11-02
Statut : acceptée

## Contexte
Les salariés réservent depuis leur navigateur. Une API REST existe déjà pour
l'application de bureau de l'accueil, et une application mobile est prévue pour 2027.
Deux options : pages rendues par Express et EJS, ou SPA React appelant l'API.

## Décision
L'interface des salariés est une SPA React (Vite), servie par Nginx, qui appelle
l'API REST existante.

## Conséquences
+ Une seule API pour tous les clients : les règles ne sont écrites qu'une fois.
+ L'application mobile pourra réutiliser l'API et une partie du code React.
+ Interface plus fluide (planning sans rechargement).
- Deux projets à construire et à déployer (front et API).
- Il faut configurer Nginx pour la SPA (try_files) et gérer l'authentification
  de l'API depuis le navigateur.