arc42 vs modèle C4 : différences et comment les combiner

Quelqu'un dans votre équipe propose arc42 pour la documentation d'architecture. Quelqu'un d'autre répond que l'équipe utilise déjà C4. La discussion qui suit suppose en général qu'il faut choisir l'un des deux, et c'est la première hypothèse à abandonner.

Comparer arc42 et C4, c'est un peu comparer le plan d'un rapport avec les graphiques qu'il contient. arc42 est un template : douze sections qui vous disent quoi documenter sur une architecture, des objectifs de qualité aux risques. C4 est un modèle et une notation : quatre niveaux de diagrammes qui vous disent comment dessiner la structure d'un système logiciel. Ils se recoupent à quelques endroits, et ils se combinent bien. Ce guide présente ce que couvre chacun, ce qu'arc42 demande et que C4 ne dessine pas, ce que C4 apporte à arc42, et une correspondance section par section indiquant quel diagramme C4 va où.

La réponse en une ligne

arc42 est un template de documentation d'architecture. Le modèle C4 est une façon de dessiner des diagrammes d'architecture logicielle. La plupart des équipes qui utilisent les deux placent des diagrammes C4 dans les sections arc42.

La FAQ d'arc42 décrit la relation de cette façon. À la question « What about arc42 and C4? », elle répond que le modèle C4 « présente de nombreuses similitudes avec quelques sections d'arc42, mais en omet certaines parties (par exemple les exigences de qualité, les concepts transversaux, les risques et quelques autres) » (arc42 FAQ, B-17). La même FAQ cite le modèle C4 de Simon Brown parmi les alternatives à arc42 (A-6), ce qui est vrai si vous n'avez besoin que de diagrammes, et trompeur si vous avez besoin de tout le reste de ce qu'un document contient.

Les douze sections d'arc42

Avant de faire correspondre quoi que ce soit, il est utile d'avoir les sections sous les yeux avec leurs numéros exacts. Elles viennent de la documentation arc42, template version 9.0 (juillet 2025, d'après la page de téléchargement) :

arc42 est explicite sur un autre point : on ne remplit pas tout. À la question « quelles parties sont essentielles ? », sa FAQ répond « Ne remplissez pas tout, s'il vous plaît. Documentez uniquement ce dont vos parties prenantes ont besoin », car tout ce que vous écrivez « demandera potentiellement un effort de maintenance à l'avenir » (B-1). Ce conseil compte pour la combinaison décrite plus bas. Un document arc42 léger avec de bons diagrammes C4 dans trois sections vaut mieux qu'un document complet que personne ne met à jour.

Ce qu'arc42 couvre et que C4 ne couvre pas

C4 traite de la structure et, via ses diagrammes complémentaires, de l'exécution et du déploiement. Il ne dit rien des parties d'une architecture qui ne sont pas des boîtes. En termes arc42, ces sections n'ont aucun équivalent C4 :

• Section 1, Introduction et objectifs. Pourquoi le système existe, qui s'y intéresse, et les trois à cinq objectifs de qualité qui orientent chaque décision ultérieure. Un diagramme de contexte C4 montre qui utilise le système. Il ne peut pas dire que « un checkout doit se terminer en moins de deux secondes » compte plus que « l'interface d'administration est jolie ».
• Section 2, Contraintes. « Doit tourner sur la plateforme Kubernetes de l'entreprise », « doit être écrit en Java », « les données ne peuvent pas quitter l'UE ». Les contraintes expliquent des choix qu'un diagramme ne fait qu'afficher.
• Section 4, Stratégie de solution. La poignée de choix fondamentaux (d'abord un monolithe, event sourcing pour le registre comptable, acheter le moteur de recherche) résumés en un seul endroit.
• Section 8, Concepts transversaux. Authentification, gestion des erreurs, logging, patterns de persistance, internationalisation. Ils traversent chaque boîte, donc aucune boîte seule ne peut les montrer.
• Section 10, Exigences de qualité. Des scénarios de qualité concrets : stimulus, réponse, mesure.
• Section 11, Risques et dette technique. Ce que vous savez fragile, et ce que vous avez reporté.
• Section 12, Glossaire. Les mots qu'emploie le métier, définis une fois.

Ce sont exactement les sections que la FAQ d'arc42 cite quand elle dit que C4 « en omet certaines parties ». Si votre documentation d'architecture se résume à des diagrammes C4, ce sont les questions qu'un nouvel architecte ou un auditeur se posera encore après l'avoir lue.

Ce que C4 apporte à arc42

arc42 n'impose volontairement aucune notation. La section 5 demande une « collection hiérarchique de boîtes noires et de boîtes blanches », la section 3 suggère « toutes sortes de diagrammes qui montrent le système comme une boîte noire », et la section 6 accepte tout, d'une liste numérotée d'étapes aux diagrammes de séquence, BPMN ou machines à états (section 5, section 3, section 6). Cette flexibilité est une force du template, et c'est aussi là que les documents arc42 varient le plus : chaque auteur dessine différemment.

C4 comble ce manque avec deux choses :

1. Un zoom cohérent. La vue en briques d'arc42 a déjà des niveaux : le niveau 1 est « la description en boîte blanche du système global, avec les descriptions en boîte noire de toutes les briques qu'il contient », et le niveau 2 « zoome sur certaines briques du niveau 1 » (section 5). Les niveaux C4 donnent à ces étapes de zoom un sens fixe (système, conteneur, composant, code), si bien qu'un lecteur qui connaît C4 sait ce qu'il regarde avant même de lire les libellés.
2. Un petit vocabulaire commun. Personne, système logiciel, conteneur, composant, relation, chacun avec un nom, une description et généralement une technologie. C'est assez de notation pour rendre les diagrammes comparables d'une équipe à l'autre, et assez peu pour que personne n'ait besoin de formation.

Il y a aussi un avantage pratique. Si les diagrammes C4 viennent d'un modèle plutôt que d'un outil de dessin, le même élément apparaît sous le même nom dans les sections 3, 5, 6 et 7. arc42 n'a pas d'avis sur la manière d'y parvenir, mais c'est ce qui rend les sections cohérentes entre elles.

Table de correspondance : quel diagramme C4 va dans quelle section arc42

Cette correspondance est la nôtre, déduite des définitions des sections d'arc42 et des définitions des diagrammes C4. La FAQ d'arc42 renvoie vers des exemples communautaires de cette combinaison (par exemple le dépôt d'exemple arc42 + C4 de bitsmuggler) plutôt que d'en imposer une, et les équipes varient sur les détails notés dans la dernière colonne.

Les sections absentes de la table (1, 2, 4, 8, 10, 11, 12) sont du texte et des tableaux, pas des diagrammes C4. Ce n'est pas une lacune de l'une ou l'autre méthode ; c'est la répartition du travail.

Exemple concret

Voici ce que donne la combinaison pour le système e-commerce de notre guide complet du modèle C4 : une single-page app React, une API gateway, des services Go pour les commandes, les produits et les utilisateurs, des bases PostgreSQL, Kafka et un service de notifications. C'est un squelette arc42 léger avec les diagrammes C4 placés, pas un document complet.

1. Introduction et objectifs
   - Objet : les clients parcourent et commandent des produits ; le personnel d'entrepôt gère le stock
   - Objectifs de qualité : (1) le checkout se termine en moins de 2 s au p95
                            (2) aucune commande n'est confirmée sans autorisation de paiement réussie
                            (3) un nouveau service peut être ajouté sans modifier les services existants

2. Contraintes
   - Tourne sur la plateforme Kubernetes de l'entreprise ; Go pour les services backend

3. Contexte et périmètre
   - Contexte métier : diagramme C4 System Context
     [Client], [Personnel d'entrepôt] -> [Plateforme e-commerce]
     -> [Stripe], [FedEx API], [SendGrid]
   - Contexte technique : tableau partenaire / protocole / données échangées

4. Stratégie de solution
   - Une base de données par service ; notifications asynchrones via Kafka

5. Vue en briques
   - Niveau 1 : diagramme C4 Container (SPA, API Gateway, services Order/Product/User,
     trois bases PostgreSQL, Kafka, Notification Service)
   - Niveau 2 : diagramme C4 Component de l'Order Service uniquement
     (Order Handler, Order Service, Order Repository, Payment Client,
     Inventory Client)

6. Vue d'exécution
   - "Le client passe une commande" : diagramme dynamique C4, 10 étapes numérotées

7. Vue de déploiement
   - Production : diagramme de déploiement C4
   - Staging : uniquement les différences avec la production

8. Concepts transversaux
   - Authentification à la gateway ; clés d'idempotence sur POST /orders ;
     logging structuré avec un request ID

9. Décisions d'architecture
   - ADR-001 Une base de données par service
   - ADR-002 Kafka pour les événements de commande plutôt que des appels synchrones
   - ADR-003 Autoriser le paiement avant d'écrire la commande

10. Exigences de qualité
   - Scénario : 500 checkouts par minute pendant les soldes, p95 sous 2 s

11. Risques et dette technique
   - Le stock est réservé avant le paiement ; pas encore de compensation en cas d'échec du paiement

12. Glossaire
   - Commande, Réservation, Autorisation, Exécution

Remarquez où se trouvent les diagrammes : sections 3, 5, 6 et 7. Tout le reste tient en quelques lignes de texte. Remarquez aussi comment le risque de la section 11 et l'ADR-003 de la section 9 renvoient à ce que montre le diagramme dynamique de la section 6. C'est dans ces renvois qu'un document combinant arc42 et C4 prouve sa valeur : le diagramme montre l'ordre des étapes, l'ADR dit pourquoi, et le risque dit ce qui ne va pas encore.

Pour le diagramme dynamique lui-même, le guide du diagramme dynamique C4 déroule ce scénario précis étape par étape. Pour la section 9, le guide complet des architecture decision records couvre le format recommandé par arc42 et la manière de tenir un index.

Si les douze sections d'arc42 vous semblent plus que ce dont votre équipe a besoin, notre template de documentation d'architecture logicielle est un plan Markdown plus court construit sur les mêmes idées, avec une section qui explique comment il se rattache à arc42.

Garder les deux à jour

arc42 et C4 partagent un mode d'échec : les deux sont excellents le jour où ils sont écrits. La FAQ d'arc42 prévient elle-même que chaque section que vous remplissez est une maintenance à laquelle vous vous engagez (B-1). Quelques habitudes qui tiennent :

• Sortez les diagrammes du corps du document quand vous le pouvez. Référencez ou intégrez des diagrammes générés à partir d'un modèle au lieu de coller des captures d'écran. Une capture d'un diagramme de conteneurs est obsolète le jour où un conteneur est renommé. Un diagramme rendu depuis le modèle n'est obsolète que si le modèle l'est.
• Placez les sections qui changent vite à côté du code. Les sections 5, 6 et 9 changent avec le code. Les sections 1, 2 et 10 changent avec le métier. Stocker le premier groupe dans le dépôt (arc42 fournit des templates Markdown et AsciiDoc pour cela) permet aux pull requests de les mettre à jour.
• Écrivez les ADR vers l'avant, ne les modifiez jamais. Une décision remplacée reçoit un nouvel ADR. La section 9 devient un historique plutôt qu'un récit réécrit.
• Donnez à chaque section un responsable et une date de revue. Un document sans responsable est un document que personne ne met à jour.
• Vérifiez les sections structurelles par rapport au code. Les sections 3 et 5 décrivent des choses qui existent dans le code, elles peuvent donc être vérifiées automatiquement. Les sections 1, 8 et 10 non ; elles ont besoin d'une revue humaine, à intervalles réguliers.

C'est sur ce dernier point qu'archyl intervient, et seulement pour une partie du problème. archyl contient le modèle C4, pas un document arc42. Sa découverte par IA propose, à partir d'un dépôt, des systèmes, conteneurs, composants et relations que vous validez, les ADR sont rattachés aux éléments C4 qu'ils affectent, et un score de dérive vérifie que les éléments documentés existent toujours dans le code. Cela couvre les sections riches en diagrammes (3, 5, 6, 9). Il n'écrit ni vos objectifs de qualité, ni vos concepts transversaux, ni votre liste de risques, et il n'y a pas d'export arc42 ; les sections de texte restent dans votre document arc42, avec des liens vers le modèle.

FAQ

arc42 est-il meilleur que C4 ?

Aucun n'est meilleur, car ils ne font pas le même travail. arc42 est un template de documentation qui couvre les objectifs, les contraintes, la structure, l'exécution, le déploiement, les décisions, la qualité et les risques. C4 est une manière de dessiner la structure de façon cohérente. Si vous avez besoin d'un document d'architecture complet, utilisez arc42 (ou quelque chose de similaire). Si vous avez besoin de diagrammes cohérents, utilisez C4. La plupart des équipes qui ont besoin des deux utilisent des diagrammes C4 dans arc42.

Peut-on utiliser arc42 et C4 ensemble ?

Oui, et c'est courant. arc42 n'impose pas de notation, donc les diagrammes C4 s'insèrent directement dans ses sections : le diagramme de contexte en section 3, les diagrammes de conteneurs et de composants en section 5, les diagrammes dynamiques en section 6 et les diagrammes de déploiement en section 7.

Où va le diagramme de conteneurs C4 dans arc42 ?

Dans la section 5, Vue en briques, au niveau 1 : la vue en boîte blanche du système entier. Les diagrammes de composants vont au niveau 2, pour les conteneurs qui en ont besoin. Si votre système est un monolithe modulaire, vos briques de niveau 1 peuvent être des modules plutôt que des conteneurs, et la correspondance est plus lâche.

arc42 impose-t-il UML ?

Non. arc42 suggère des notations dans plusieurs sections (la section 3 mentionne par exemple un diagramme de déploiement UML pour le contexte technique) mais vous laisse le choix. C4, UML et de simples boîtes et flèches sont tous utilisés avec lui.

Où vont les ADR dans arc42 ?

Dans la section 9, Décisions d'architecture. arc42 recommande lui-même un ADR pour chaque décision importante, dans la structure de Michael Nygard, et permet de documenter une décision localement dans la brique qu'elle affecte si c'est plus lisible.

arc42 est-il gratuit ?

Oui. Le template est gratuit et open source, sous licence CC BY-SA 4.0, et disponible en douze langues et formats, dont AsciiDoc, Markdown, Word et Confluence (page de téléchargement).

Vous voulez que la moitié C4 de votre document arc42 reste fidèle au code ? Essayez archyl gratuitement et générez le modèle à partir de votre dépôt. À lire ensuite : Qu'est-ce que le modèle C4 ? Le guide complet | Architecture Decision Records : le guide complet | Guide du diagramme dynamique C4 | Template de documentation d'architecture logicielle.