Template de documentation d'architecture logicielle (gratuit)

Voici comment un document d'architecture est habituellement écrit : un nouvel ingénieur arrive, demande comment le système s'articule, et quelqu'un promet de « mettre tout ça au propre ». Il cherche un template de documentation d'architecture logicielle, trouve un fichier Word de quarante pages datant de 2012 ou un PDF universitaire, en remplit la moitié et ne l'ouvre plus jamais. Un an plus tard, la recrue suivante le trouve, lui fait confiance et se trompe.

Le problème est rarement l'absence de template. Ce sont des templates qui demandent tout, si bien que rien n'est terminé, et des documents sans responsable, si bien que rien n'est mis à jour. Le template ci-dessous est volontairement léger : un fichier Markdown, neuf sections, chacune présente parce que quelqu'un qui le lira en aura besoin. Copiez-le dans votre dépôt, sans inscription ni téléchargement. Lisez ensuite les notes section par section sur ce qui va dans chaque partie, et sur la façon d'éviter qu'il devienne obsolète.

À quoi sert un document d'architecture (et qui le lit)

Un document d'architecture répond aux questions auxquelles le code ne répond pas vite : à quoi sert le système, avec quoi il communique, comment il est découpé, pourquoi il est découpé ainsi, et ce qui est connu pour être fragile. Ce n'est pas une spécification de conception pour une fonctionnalité, ni une référence d'API.

Il a cinq types de lecteurs, et il est utile d'écrire en les ayant nommément en tête :

Si une section de votre document ne sert aucun d'entre eux, supprimez-la. Cette règle fait plus pour la qualité de la documentation que n'importe quel template.

Un mot sur les noms : « document d'architecture », « system design document » (SDD) et « software architecture document » (SAD) désignent à peu près la même chose. Les templates de SDD sont généralement écrits par projet ou par fonctionnalité et incluent la conception détaillée ; un document d'architecture décrit le système tel qu'il est et évolue avec lui. Le template présenté ici est du second type.

Le template (un bloc Markdown)

Copiez-le dans docs/architecture.md (ou ARCHITECTURE.md à la racine) et remplissez-le. Tout ce qui est entre chevrons est à remplacer. Supprimez toute section qui ne s'applique pas plutôt que de la laisser vide.

# <Nom du système> : architecture

| | |
|---|---|
| Responsable | <équipe ou personne chargée de garder ce document juste> |
| Dernière revue | <AAAA-MM-JJ> |
| Prochaine revue | <AAAA-MM-JJ, ou "à chaque changement des sections 3-5"> |
| Statut | <brouillon / à jour / en cours de remplacement par X> |

## 1. Contexte et périmètre

<Deux ou trois phrases : ce que fait le système, pour qui, et pourquoi il existe.>

**Utilisateurs**
- <Rôle> : <ce qu'ils font avec le système>

**Systèmes externes**
- <Système> : <ce que nous envoyons ou recevons, protocole>

**Hors périmètre**
- <Ce que l'on croit que ce système fait, alors qu'il ne le fait pas>

**Diagramme de contexte système (niveau C4 1)**
<Lien ou intégration. Le système en une boîte, chaque type d'utilisateur, chaque système externe.>

## 2. Objectifs de qualité

Les trois à cinq qualités qui l'emportent quand elles entrent en conflit, par ordre de priorité.

| Priorité | Qualité | Scénario concret |
|---|---|---|
| 1 | <ex. Disponibilité> | <ex. Le checkout continue de fonctionner quand le service de recommandations est en panne> |
| 2 | <ex. Latence> | <ex. p95 du checkout sous 2 s à 500 commandes/minute> |
| 3 | <ex. Évolutivité> | <ex. Un nouveau moyen de paiement est livré sans toucher à l'order service> |

## 3. Contraintes

Ce que nous n'avons pas choisi mais avec quoi nous devons vivre.
- <ex. Tourne sur la plateforme Kubernetes de l'entreprise>
- <ex. Les données clients restent dans l'UE>
- <ex. Services backend uniquement en Go ou en Java>

## 4. Architecture

**Diagramme de conteneurs (niveau C4 2)**
<Lien ou intégration. Chaque unité déployable et chaque stockage de données, avec technologies et protocoles.>

| Conteneur | Technologie | Responsabilité | Responsable |
|---|---|---|---|
| <Application web> | <SPA React> | <Ce qu'il fait> | <Équipe> |
| <API> | <Go> | <Ce qu'il fait> | <Équipe> |
| <Base de données> | <PostgreSQL> | <Ce qu'elle stocke> | <Équipe> |

**Diagrammes de composants (niveau C4 3)**
<Uniquement pour le ou les deux conteneurs avec lesquels un nouvel arrivant aurait du mal. Lien ou intégration.>

**Flux clés**
<Les deux ou trois scénarios les plus importants, en étapes numérotées ou en diagramme dynamique C4.>

1. <Acteur> -> <Conteneur> : <ce qui se passe>
2. <Conteneur> -> <Conteneur> : <ce qui se passe, protocole, synchrone ou asynchrone>

## 5. Décisions clés

Les records complets sont dans <docs/adr/>. Ceci est l'index.

| ADR | Décision | Statut | Date |
|---|---|---|---|
| [ADR-001](adr/001-<slug>.md) | <ex. Une base de données par service> | Acceptée | <AAAA-MM-JJ> |
| [ADR-002](adr/002-<slug>.md) | <ex. Kafka pour les événements de commande> | Acceptée | <AAAA-MM-JJ> |

## 6. Préoccupations transversales

Comment l'ensemble du système gère ce que chaque conteneur touche. Une ou deux lignes chacune, avec un lien vers le détail.
- **Authentification et autorisation :** <où elle a lieu, quel token>
- **Observabilité :** <logs, métriques, traces, où regarder>
- **Gestion des erreurs et retries :** <conventions, idempotence>
- **Données et confidentialité :** <emplacement des données personnelles, rétention>

## 7. Déploiement et exploitation

- **Environnements :** <production, staging, ...> et leurs différences
- **Où il tourne :** <cloud, région, cluster>
- **Runbooks :** <lien>
- **Dashboards et alertes :** <lien>

## 8. Risques et dette technique

| Risque ou dette | Impact s'il se réalise | Plan | Responsable |
|---|---|---|---|
| <ex. Stock réservé avant le paiement, sans compensation> | <Réservations fantômes après des échecs de paiement> | <Ajouter la libération en cas d'échec, T4> | <Équipe> |

## 9. Glossaire

| Terme | Sens ici |
|---|---|
| <Commande> | <Définition telle que le métier l'emploie> |

C'est tout le template. Rempli pour un système d'une dizaine de conteneurs, il fait généralement quelques pages. Si le vôtre est bien plus long, une partie de son contenu a probablement sa place dans un document lié plutôt que dans celui-ci.

Section par section

En-tête : responsable et date de revue

Les quatre lignes du haut comptent plus que n'importe quelle section en dessous. Responsable dit qui corrige le document quand il est faux. Dernière revue dit au lecteur à quel point il peut s'y fier. Un document qui indique « dernière revue il y a quatorze mois » est honnête ; un document qui n'indique rien a l'air à jour alors qu'il ne l'est pas.

1. Contexte et périmètre

Commencez ici, car toutes les autres sections dépendent de la frontière. Listez chaque type d'utilisateur et chaque système externe, y compris ceux qui vous semblent aller de soi (fournisseur d'identité, service d'email, passerelle de paiement). La liste hors périmètre évite plus de réunions que tout le reste du document : c'est là que vous écrivez que ce système ne gère pas les remboursements, même si tout le monde suppose le contraire.

Le diagramme est un diagramme de contexte système C4 : votre système en une boîte, les utilisateurs et les systèmes externes autour, des flèches annotées. Le guide du diagramme de contexte système explique ce qui y a sa place.

2. Objectifs de qualité

La plupart des documents d'architecture sautent cette section, alors que c'est elle qui explique le reste. « La disponibilité avant la cohérence » ou « l'évolutivité avant la performance brute » dit au lecteur pourquoi les conteneurs ont cette forme. Limitez-vous à trois à cinq objectifs, classez-les, et donnez à chacun un scénario assez concret pour être testé : un chiffre, une charge, une panne.

3. Contraintes

Les contraintes sont les décisions prises par quelqu'un d'autre : l'équipe plateforme, le juridique, la politique de langages de l'entreprise. Les écrire met fin à la conversation « pourquoi vous n'avez pas simplement utilisé X ? », et indique à un futur lecteur quels choix peuvent être revus et lesquels non.

4. Architecture : les diagrammes C4

C'est la section que la plupart des gens considèrent comme « l'architecture ». Utilisez le modèle C4, parce qu'il donne à chaque diagramme une seule mission :

• Diagramme de conteneurs (niveau 2), toujours. Chaque unité déployable et chaque stockage de données, chacun avec sa technologie, chaque flèche avec un protocole. Si vous ne dessinez qu'un diagramme, dessinez celui-là. Le guide du diagramme de conteneurs contient un exemple complet.
• Diagrammes de composants (niveau 3), de façon sélective. Uniquement pour les conteneurs avec lesquels un nouvel arrivant aurait du mal.
• Flux clés. Deux ou trois scénarios en étapes numérotées. Un diagramme statique montre que deux conteneurs se parlent ; un flux montre dans quel ordre, et quelles étapes l'utilisateur attend. Le guide du diagramme dynamique C4 montre comment en écrire un.

Le tableau des conteneurs avec une colonne Responsable est là exprès. Un conteneur qui n'appartient à personne est un conteneur que personne ne mettra à jour dans ce document non plus.

Si vous découvrez C4, ce qu'est le modèle C4 explique les quatre niveaux. Pour des exemples de ces diagrammes appliqués à de vrais grands systèmes, voir nos exemples de modèle C4.

5. Décisions clés (ADR)

N'écrivez pas les décisions dans le corps du texte. Consignez chacune comme un architecture decision record dans son propre fichier (contexte, décision, alternatives envisagées, conséquences) et ne gardez ici que l'index. Les ADR sont écrits une fois puis remplacés plutôt que modifiés, si bien que le document reste court et l'historique intact. Le guide complet des architecture decision records couvre le format et indique quand une décision mérite un ADR.

Un bon test pour l'index : un nouvel ingénieur doit pouvoir pointer n'importe quelle boîte surprenante de la section 4 et trouver l'ADR qui l'explique.

6. Préoccupations transversales

Certaines choses ne vivent dans aucun conteneur en particulier : l'authentification, le logging, la gestion des erreurs, l'emplacement des données personnelles. Une ou deux lignes chacune suffisent, avec un lien vers le détail. C'est dans cette section qu'un auditeur passe le plus de temps, alors facilitez-lui la tâche.

7. Déploiement et exploitation

Restez bref et renvoyez vers l'extérieur. Les environnements et leurs différences, où tourne le système, et des liens vers les runbooks et les dashboards. Le détail a sa place dans votre code d'infrastructure et vos runbooks, qui changent plus souvent que ce document ne devrait le faire.

8. Risques et dette technique

La section honnête. Écrivez ce qui est connu pour être fragile, avec un responsable et un plan, même si le plan est « accepté, à revoir au T3 ». Un risque écrit est un risque que quelqu'un peut prioriser. Un risque qui vit dans la tête d'un seul ingénieur part avec lui.

9. Glossaire

Chaque système a des mots qui ont ici un sens précis : « commande » vs « panier », « compte » vs « tenant », « exécution ». Définissez chacun une fois. Les nouveaux ingénieurs lisent cette section plus qu'on ne le pense.

Le lien avec arc42

Si ce template vous semble familier, c'est qu'il s'agit d'une version allégée des mêmes idées qu'arc42, le template de documentation d'architecture gratuit et open source créé par Peter Hruschka et Gernot Starke. arc42 compte douze sections et conseille lui-même de documenter « uniquement ce dont vos parties prenantes ont besoin » (arc42 FAQ, B-1). La correspondance :

Choisissez arc42 quand vous avez besoin de sa structure complète : environnements réglementés, grands systèmes avec plusieurs architectes, ou une organisation qui l'a déjà standardisé. Choisissez quelque chose de cette taille quand l'alternative est de n'avoir aucun document. Pour une comparaison détaillée, y compris quel diagramme C4 va dans quelle section arc42, voir arc42 vs C4.

Éviter qu'il devienne obsolète

Tout document d'architecture est exact le jour où il est mergé. Qu'il le soit encore dans six mois dépend de quelques habitudes, la plupart liées aux diagrammes, car c'est dans les sections 4 et 5 que la réalité change le plus vite.

Gardez-le dans le dépôt. docs/architecture.md à côté du code signifie qu'une pull request qui découpe un service peut mettre à jour le tableau des conteneurs dans la même revue. Une page de wiki ne peut pas faire partie d'une revue de code.

Liez les diagrammes, ne collez pas de captures d'écran. Une capture du diagramme de conteneurs est obsolète dès qu'un conteneur est renommé. Un diagramme rendu à partir d'un modèle (DSL Structurizr, un modèle YAML ou un outil qui en contient un) n'est obsolète que si le modèle l'est.

Faites travailler la date de revue. Ajoutez le document à toute checklist qui s'exécute quand un conteneur est ajouté ou supprimé : le template de pull request, la revue d'architecture, la planification trimestrielle. « Prochaine revue : à chaque changement des sections 3 à 5 » est une entrée valable.

Écrivez les décisions vers l'avant. Ne modifiez jamais un ADR accepté. Remplacez-le. L'index de la section 5 montre alors l'historique, qui est la partie dont les gens ont le plus besoin.

Vérifiez automatiquement les parties structurelles. Les sections 1 et 4 décrivent des choses qui existent dans le code : services, stockages de données, dépendances. Elles peuvent être comparées au dépôt. Les sections 2, 6 et 8 non, et elles ont besoin d'une personne, à intervalles réguliers. Le guide de détection de la dérive d'architecture présente les méthodes pour la première catégorie et ce que chacune peut ou ne peut pas voir.

C'est le problème pour lequel archyl est conçu, pour la moitié diagrammes du document. Connectez un dépôt et la découverte par IA propose le modèle C4 (systèmes, conteneurs, composants et relations) que vous relisez et validez au lieu de le dessiner. Les ADR, les docs et les flows sont liés aux éléments qu'ils décrivent. Un score de dérive vérifie ensuite que les éléments documentés existent toujours dans le code, de façon déterministe et sans IA dans la boucle, si bien qu'une section 4 obsolète apparaît sous forme de chiffre plutôt que de mauvaise surprise. Il ne vérifie ni vos objectifs de qualité ni votre liste de risques ; ceux-là ont toujours besoin de la date de revue. Pour les pratiques qui gardent la documentation à jour, avec ou sans outil, voir la documentation d'architecture vivante.

FAQ

Que doit contenir un document d'architecture logicielle ?

Au minimum : le contexte et le périmètre du système (utilisateurs et systèmes externes), un diagramme au niveau des conteneurs avec les technologies, les décisions d'architecture clés avec leurs raisons, les risques connus, et un responsable avec une date de revue. Le template ci-dessus ajoute les objectifs de qualité, les contraintes, les préoccupations transversales, des notes de déploiement et un glossaire, le tout en version courte.

Ce template est-il vraiment gratuit ?

Oui. C'est le bloc Markdown ci-dessus. Copiez-le et adaptez-le à votre système. Pas d'inscription, pas de téléchargement, pas d'email.

Où le document d'architecture doit-il se trouver ?

Dans le dépôt, sous docs/architecture.md ou ARCHITECTURE.md, à côté des ADR dans docs/adr/. Ainsi, les changements d'architecture et les changements du document passent par la même pull request.

Quelle longueur doit faire un document d'architecture ?

Aussi court que possible tout en répondant aux questions de ses lecteurs. Pour un système d'une dizaine de conteneurs, quelques pages sont normales. S'il grossit bien au-delà, déplacez le détail dans des documents liés (runbooks, ADR, références d'API) et gardez celui-ci comme carte.

Quelle différence avec un system design document ?

Un system design document est généralement écrit pour un projet ou une fonctionnalité, avant sa construction, et inclut la conception détaillée. Un document d'architecture décrit le système entier tel qu'il est aujourd'hui et évolue avec lui. Les équipes ont souvent un document d'architecture par système et de nombreux documents de conception au fil de sa vie, les décisions durables de ces derniers finissant en ADR.

Devrais-je plutôt utiliser arc42 ?

Si vous avez besoin de sa structure complète ou si votre organisation l'utilise déjà, oui. Ce template correspond aux sections d'arc42 (voir le tableau ci-dessus), vous pouvez donc commencer ici et passer à arc42 plus tard sans rien réécrire.

Vous voulez que les diagrammes de la section 4 viennent de votre code plutôt que de votre mémoire ? Essayez archyl gratuitement avec le plan Developer, sans carte bancaire. À lire ensuite : arc42 vs C4 | Architecture Decision Records : le guide complet | Qu'est-ce que le modèle C4 ? | La documentation d'architecture vivante | Détection de la dérive d'architecture.