Backstage vs Archyl : Deux approches de la documentation d'architecture

Si vous évaluez des outils pour la documentation d'architecture, vous avez probablement regardé Backstage. C'est open-source, c'est soutenu par Spotify, et son écosystème de plugins couvre tout, du CI/CD à la gestion des coûts. L'un de ces plugins gère les diagrammes C4.

Archyl prend l'approche inverse. Ce n'est pas un portail développeur. Il ne gère pas les pipelines CI ni les catalogues de services. Il fait une seule chose : la documentation d'architecture avec le modèle C4 — et il va en profondeur sur ce sujet.

Cet article n'est pas un « quel outil est meilleur ». Ils servent des objectifs différents. Mais si ce dont vous avez réellement besoin est la documentation d'architecture, les différences comptent. Laissez-moi les détailler.

La philosophie fondamentale

Backstage est un framework de portail développeur. Son rôle est d'unifier tous les outils, services et documentations qu'une équipe de développement utilise dans une seule plateforme interne. La documentation d'architecture est l'un des nombreux plugins disponibles — c'est une fonctionnalité au sein d'un écosystème plus large.

Archyl est une plateforme de documentation d'architecture conçue de A à Z. L'ensemble du produit existe pour modéliser, visualiser, analyser et faire évoluer l'architecture logicielle à l'aide du modèle C4. Chaque fonctionnalité alimente cet objectif unique.

Cette différence de périmètre façonne tout le reste.

Support du modèle C4

Backstage

Le modèle d'entités de Backstage inclut des Components, APIs, Resources, Systems, Domains, Groups et Users. Cela correspond approximativement aux niveaux C4 1 et 2 — systèmes et conteneurs. Mais la correspondance est approximative, pas précise.

Le plugin C4 pour Backstage (backstage-plugin-c4-model) génère des diagrammes à partir des entités du catalogue existant. Il supporte les vues Contexte Système et Conteneur. Il n'y a pas de support natif pour le C4 Niveau 3 (Composants) ou Niveau 4 (Code). Si votre modélisation architecturale doit descendre sous le niveau conteneur, vous êtes bloqué.

Le catalogue lui-même est piloté par YAML. Chaque entité est définie dans des fichiers catalog-info.yaml, généralement committés à côté du code. Cela signifie que l'architecture est définie dans des fichiers de configuration, pas dans un outil visuel.

Archyl

Archyl implémente nativement les quatre niveaux C4 :

• Niveau 1 — Contexte Système : Systèmes, systèmes externes et personnes
• Niveau 2 — Conteneur : Applications, services, bases de données, files de messages, caches, et plus
• Niveau 3 — Composant : Contrôleurs, services, repositories, handlers, middleware, modèles
• Niveau 4 — Code : Classes, interfaces, fonctions, méthodes, enums, constantes

Chaque niveau possède ses propres types de nœuds, styles visuels et métadonnées. Vous pouvez descendre d'un système vers ses conteneurs, d'un conteneur vers ses composants, d'un composant vers ses éléments de code — le tout dans le même diagramme interactif. Les relations entre éléments à n'importe quel niveau sont des citoyens de première classe avec des connexions typées (uses, depends_on, calls, reads_from, writes_to, etc.).

La différence : Backstage vous donne un catalogue avec des vues C4 ajoutées par-dessus. Archyl vous donne un environnement de modélisation C4 complet où vous pouvez représenter l'intégralité de votre architecture à n'importe quel niveau de détail.

Visualisation

Backstage

Le plugin C4 génère des diagrammes statiques ou semi-interactifs à partir des données du catalogue. La visualisation dépend de l'implémentation du plugin — certains utilisent PlantUML, d'autres Structurizr, d'autres rendent dans le navigateur. Mais l'expérience est fondamentalement en lecture seule. Vous visualisez des diagrammes générés depuis des définitions YAML. Vous n'interagissez pas avec eux.

Il n'y a pas de manipulation de canvas, pas de positionnement par glisser-déposer, pas de collaboration en temps réel sur les diagrammes. Pour modifier la représentation de l'architecture, vous éditez des fichiers YAML et attendez que le catalogue se rafraîchisse.

Archyl

Archyl fournit un canvas entièrement interactif construit sur React Flow. Vous pouvez :

• Déplacer et positionner n'importe quel élément sur le diagramme
• Dessiner des relations entre éléments directement sur le canvas
• Naviguer entre les niveaux C4 en entrant dans les systèmes, conteneurs et composants
• Voir les curseurs en temps réel de vos collègues travaillant sur le même diagramme
• Utiliser l'auto-layout pour arranger les éléments automatiquement, ou les positionner manuellement
• Appliquer des overlays pour regrouper visuellement des éléments liés
• Basculer entre thèmes clair et sombre sur le diagramme

Le canvas est l'espace de travail principal, pas un artéfact généré. Chaque modification que vous faites sur le diagramme se reflète instantanément.

Découverte assistée par IA

Backstage

Backstage n'a pas de découverte d'architecture assistée par IA intégrée. Pour peupler le catalogue, vous créez manuellement des fichiers catalog-info.yaml pour chaque service, ou utilisez des fournisseurs d'entités qui importent depuis des sources externes (Kubernetes, GitHub, etc.). Certains plugins communautaires ajoutent des capacités IA, mais il n'y a pas d'analyse native d'architecture depuis le code.

Si vous avez 200 services et qu'aucun n'a de fichier catalog-info.yaml, vous écrivez 200 fichiers YAML à la main — ou vous construisez des outils personnalisés pour les générer.

Archyl

Archyl inclut une découverte IA intégrée qui se connecte à votre dépôt Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, ou dépôts locaux), lit votre code source, et génère automatiquement un modèle C4 complet.

Le pipeline de découverte :

1. Se connecte à votre dépôt
2. Analyse les fichiers sources, le code d'infrastructure et la configuration
3. Identifie les systèmes, conteneurs, composants et leurs relations
4. Détecte les dépendances depuis les manifestes de packages
5. Génère un modèle C4 proposé avec auto-layout
6. Présente le résultat pour votre revue et approbation

Vous pouvez approuver, modifier ou rejeter n'importe quelle partie du modèle généré. L'IA gère le gros du travail de cartographie initiale de l'architecture ; vous apportez le jugement.

Le système comprend Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, Kubernetes YAML, les charts Helm, et plus encore.

Architecture Decision Records

Backstage

Les ADRs dans Backstage sont généralement gérés via le plugin ADR, qui lit des fichiers markdown ADR depuis un dépôt. Il les affiche dans l'interface Backstage, souvent en suivant le format MADR (Markdown Architectural Decision Records). Les ADRs vivent dans Git comme des fichiers markdown.

Il n'y a pas de lien entre les ADRs et les entités du catalogue. Un ADR sur le choix de PostgreSQL plutôt que MongoDB se trouve dans un dossier /docs/adr/ — il n'y a pas de connexion directe avec le conteneur de base de données qu'il référence.

Archyl

Les ADRs dans Archyl sont des objets de première classe liés directement aux éléments C4. Quand vous créez un ADR, vous pouvez l'attacher à des systèmes, conteneurs, composants ou éléments de code spécifiques. Cela signifie :

• Ouvrez un conteneur sur le diagramme, et vous voyez ses ADRs associés
• Parcourez les ADRs et voyez exactement quels éléments d'architecture ils affectent
• Comprenez le raisonnement derrière les choix architecturaux en contexte

Les ADRs supportent des statuts (proposé, accepté, déprécié, remplacé) et un contenu markdown riche avec des sections structurées pour le contexte, la décision et les conséquences.

Documentation

Backstage

Le système TechDocs de Backstage convertit des fichiers markdown (généralement via MkDocs) en documentation navigable au sein du portail. C'est basé sur markdown et stocké dans Git. La documentation se rend bien et supporte la recherche.

Cependant, TechDocs est de la documentation généraliste, pas de la documentation d'architecture. Il n'y a pas de connexion structurelle entre les docs et le modèle d'architecture. Une page sur « l'Architecture d'Authentification » ne fait pas de lien vers le système d'authentification sur le diagramme.

Archyl

Le système de documentation d'Archyl est intégré avec le modèle d'architecture. Les éléments de documentation peuvent être liés aux éléments C4, organisés en dossiers, et accessibles en contexte à côté des diagrammes. Quand vous visualisez un système ou un conteneur, sa documentation associée est visible dans le panneau latéral.

Il ne s'agit pas de remplacer les outils de documentation généralistes. Il s'agit de s'assurer que la documentation d'architecture vit à côté de l'architecture qu'elle décrit.

Analyse d'impact

Backstage

Backstage n'a pas de capacité d'analyse d'impact. Si vous voulez comprendre ce qui casse quand vous dépréciez un service, vous tracez manuellement les dépendances à travers le catalogue. Il n'y a pas d'analyse automatisée amont/aval, pas de score de risque, pas de simulation de scénarios.

Certaines organisations construisent des scripts ou plugins personnalisés pour analyser les relations du catalogue, mais il n'y a rien d'intégré.

Archyl

L'Impact Radar d'Archyl fournit une analyse d'impact complète directement sur le diagramme. Faites un clic droit sur n'importe quel élément et voyez instantanément :

• Dépendants amont et dépendances aval organisés par degré (1, 2, 3 sauts)
• Score de risque calculé à partir des dépendants amont, la portée aval, les enfants structurels et le ratio de couplage
• Chemin critique mettant en évidence la plus longue chaîne de dépendances
• Dépendances inter-projets avec l'Architecture Globale
• Flux impactés croisés avec les parcours utilisateur documentés
• Simulation de scénarios montrant exactement ce qui casse si un élément est supprimé

L'analyse s'exécute de manière déterministe sur le graphe de relations. Pas de suppositions, pas de réunions pour déterminer qui est affecté.

Gestion du changement

Backstage

Les changements au catalogue Backstage passent par Git. Vous créez une PR qui modifie catalog-info.yaml, la faites relire, et la mergez. C'est le workflow Git standard — il n'y a pas de gestion du changement spécifique à l'architecture.

La revue se fait dans GitHub/GitLab, pas dans le contexte de l'architecture. Les relecteurs voient des diffs YAML, pas des diffs visuels de comment l'architecture change.

Archyl

Archyl dispose de Demandes de changement d'architecture dédiées — un workflow de type pull-request spécifiquement pour les changements d'architecture. Vous proposez des modifications au modèle C4, les relecteurs voient exactement ce qui est ajouté, modifié ou supprimé, et le changement passe par un processus d'approbation avant d'être appliqué.

Cela apporte de la gouvernance à l'évolution de l'architecture sans forcer tout à passer par des fichiers YAML et des diffs Git.

Collaboration

Backstage

Backstage est un portail web. Plusieurs personnes peuvent y accéder simultanément, mais il n'y a pas de collaboration en temps réel sur l'architecture elle-même. Vous consultez le catalogue indépendamment. Il n'y a pas de curseurs en direct, pas d'indicateurs de présence, pas d'édition concurrente.

Archyl

Archyl fournit une collaboration en temps réel sur les diagrammes C4 :

• Curseurs en direct montrant où vos collègues se trouvent sur le canvas
• Indicateurs de présence montrant qui visualise le diagramme
• Suivi du focus pour voir quels éléments vos collègues modifient
• Édition concurrente avec résolution de conflits

Cela s'étend aussi bien aux diagrammes C4 au niveau projet qu'à la vue Architecture Globale.

Données opérationnelles en temps réel

L'une des plus grandes surprises quand on découvre Archyl, c'est le Marketplace. La documentation d'architecture n'est pas que des diagrammes statiques — Archyl se connecte aux outils que vos équipes utilisent déjà et affiche des données en direct directement sur votre architecture.

Backstage

L'écosystème de plugins de Backstage est sa force principale ici. Il existe des plugins pour presque tout — statut CI/CD, tableaux de bord de monitoring, suivi des coûts, statut Kubernetes, et plus encore. Mais ces plugins vivent dans leurs propres pages au sein du portail. Ils ne sont pas connectés à la vue architecture. Vous voyez le statut CI/CD d'un service sur sa page catalogue, mais pas sur le diagramme C4 où ce service vit en contexte avec tout ce dont il dépend.

Archyl

Le Marketplace d'Archyl fournit des intégrations qui affichent des données en direct sous forme de widgets directement sur vos tableaux de bord d'architecture :

• CI/CD : Statut des workflows GitHub Actions, PRs ouvertes, alertes Dependabot, scanning de sécurité. Statut des pipelines GitLab, merge requests, rapports de vulnérabilités, alertes SAST/DAST. Statut des applications Argo CD et suivi des déploiements.
• Observabilité : Tableaux de bord Datadog intégrés, requêtes de métriques, statut des moniteurs. Requêtes instantanées et temporelles Prometheus, santé des cibles. Suivi d'erreurs Sentry.
• Qualité du code : Statut du quality gate SonarQube, mesures du code, issues, hotspots de sécurité et notations.
• Gestion d'incidents : Statut des incidents PagerDuty, incidents actifs, planning d'astreinte, santé des services.

Les widgets se rafraîchissent automatiquement et peuvent être scopés à trois niveaux — organisation, par projet, ou attachés à un élément C4 spécifique. Un conteneur représentant votre service de paiement peut afficher son statut de build GitHub Actions, son quality gate SonarQube, ses métriques de santé Datadog et son planning d'astreinte PagerDuty, le tout au même endroit.

Cela transforme la documentation d'architecture d'une référence statique en une vue opérationnelle vivante. Le diagramme ne montre pas seulement à quoi ressemble votre système — il montre comment il se porte en ce moment.

Au-delà des bases

Quelques domaines supplémentaires où les approches divergent :

Quand choisir quoi

Choisissez Backstage si vous avez besoin d'un portail développeur unifié qui agrège documentation, CI/CD, catalogue de services, gestion des coûts et des dizaines d'autres préoccupations dans une seule plateforme interne. La documentation d'architecture est une pièce de ce puzzle, et une vue C4 de haut niveau suffit à vos besoins.

Choisissez Archyl si la documentation d'architecture est une préoccupation primaire — mais sans sacrifier la visibilité opérationnelle pour autant. Archyl va en profondeur sur le modèle C4 (les 4 niveaux), les diagrammes interactifs, la découverte IA, l'analyse d'impact et la gouvernance du changement, tandis que ses intégrations Marketplace apportent le statut CI/CD, le monitoring, la qualité du code et les données d'incidents directement sur votre architecture. Vous obtenez un outillage d'architecture ciblé sans perdre le contexte opérationnel que Backstage fournit via son écosystème de plugins.

Ils peuvent aussi coexister. Archyl gère la modélisation architecturale détaillée, l'analyse et la visibilité opérationnelle scopée à votre architecture. Backstage gère l'expérience développeur plus large — onboarding, recherche dans le catalogue, tableaux de bord de coûts et documentation générale. Le modèle d'architecture dans Archyl peut alimenter ce que vous documentez dans le catalogue de services de Backstage, sans que l'un remplace l'autre.

En résumé

Backstage est un framework de plateforme que vous assemblez à partir de plugins. C'est puissant, flexible, et résout le problème de la fragmentation de l'expérience développeur. Mais ses capacités de documentation d'architecture se limitent à ce que les plugins C4 pilotés par catalogue peuvent offrir — typiquement les niveaux 1 et 2, des vues statiques, pas d'IA, pas d'analyse d'impact, pas de collaboration en temps réel sur les diagrammes.

Archyl est un outil ciblé qui va en profondeur sur l'architecture. Il couvre le modèle C4 complet, la découverte IA, l'analyse d'impact, la gouvernance du changement, la collaboration en temps réel — et se connecte à vos outils CI/CD, d'observabilité, de qualité de code et de gestion d'incidents pour que votre architecture reste ancrée dans la réalité opérationnelle. Ce n'est pas un portail développeur, mais c'est bien plus que de la documentation statique.

Votre architecture mérite plus qu'une entrée de catalogue.

Nouveau dans le modèle C4 ? Commencez par notre Introduction au modèle C4. Vous modélisez déjà ? Essayez la Découverte d'architecture assistée par IA pour démarrer votre premier projet depuis le code, ou explorez Impact Radar pour comprendre un changement avant de le faire.