Transformez votre catalogue Backstage en véritable architecture C4 en 60 secondes

Backstage, c'est le catalogue. Si vous travaillez dans une équipe plateforme, il y a fort à parier que vous avez passé des mois à peaufiner vos fichiers catalog-info.yaml, à configurer les annotations, à corriger les liens dependsOn, et à répondre aux questions Slack du genre « pourquoi mon service n'apparaît pas ? ». Ce travail est réel. Il représente une véritable cartographie de vos systèmes.

Mais voici le problème : Backstage a été conçu pour lister vos logiciels, pas pour les modéliser. Les pages de composants sont utiles. Les relations sont éparses. Le plugin C4 est un ajout secondaire. Vous pouvez faire défiler 700 services dans une liste plate, mais vous ne voyez pas comment ils s'imbriquent.

Pour obtenir une véritable vue d'architecture, vous aviez le choix : reconstruire votre catalogue à la main dans un autre outil, ou vous contenter de ce que Backstage propose.

Aujourd'hui, ce choix disparaît.

Archyl importe désormais votre Software Catalog Backstage directement. Un curl, un upload, et chaque System, Component, Resource et API que vous avez déjà soigneusement curé apparaît comme un modèle C4 complet et navigable — relations, contrats OpenAPI, ressources d'infrastructure et métadonnées intacts.

Soixante secondes, trois étapes

Backstage expose son catalogue d'entités complet via un seul endpoint REST. Récupérez-le, déposez-le dans Archyl, c'est tout.

Étape 1 — Exportez votre catalogue

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

C'est tout l'export. L'endpoint diffuse toutes les entités que Backstage connaît : Systems, Components, Resources, APIs, Groups, Users — tout. Pour la plupart des organisations, vous obtenez un tableau JSON de 5 à 30 Mo avec des milliers d'entrées.

Si vous testez sans authentification (certaines instances Backstage autorisent les lectures publiques sur le réseau interne), vous pouvez retirer le header Authorization. Si vous avez besoin de filtrer par kind pour réduire la taille du fichier, Backstage prend en charge des paramètres de requête : ?filter=kind=component,kind=system,kind=api,kind=resource limitera la réponse à ce qu'Archyl mappe réellement.

Étape 2 — Ouvrez la fenêtre d'import

Dans Archyl, cliquez sur Importer un projet (ou Importer dans un projet existant), sélectionnez l'onglet Backstage, puis uploadez entities.json ou collez-le directement.

Archyl valide le fichier, puis vous montre exactement ce qui sera créé — nombre de systèmes, conteneurs, contrats d'API, relations — avant que rien ne soit écrit.

Étape 3 — Cliquez sur Importer

Votre projet est rempli. Un catalogue de 9 Mo avec ~3 000 entités s'importe en quelques secondes. Vous pouvez maintenant cliquer sur n'importe quel système, voir ses conteneurs disposés au niveau C4 Level 2, plonger dans les APIs, et suivre les arêtes dependsOn à travers votre stack.

Ce qui est réellement mappé

La partie difficile de l'import depuis Backstage n'est pas de lire le JSON — c'est de traduire entre deux modèles mentaux différents. Backstage pense en termes d'entités plates connectées par des relations typées. Le C4 pense en termes de niveaux imbriqués. Voici comment Archyl fait le pont :

Backstage Archyl Notes
System C4 System (Niveau 1) Les systèmes du même nom dans des namespaces différents sont auto-désambiguïsés
Component Container sous son System propriétaire service → service, cronworkflow → worker, website → web_app
Resource Container sous son System propriétaire Type-aware : s3-bucket → file_storage ; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database ; kafka-topic, sqs-queue → message_queue ; repository → library
API (avec spec.definition) Contrat d'API Les specs OpenAPI 3, gRPC, GraphQL, AsyncAPI sont préservées inline et liées aux composants providers/consumers
dependsOn, dependencyOf Relation depends_on Les paires bidirectionnelles sont automatiquement dédupliquées
consumesApi Relation uses Résolue à travers l'API jusqu'à son composant provider réel
producesTo, producedBy Relation publishes_to
consumesFrom, consumedBy Relation consumes_from
versionedIn, versions Relation depends_on Étiquetée « source code »
metadata.namespace, spec.lifecycle, spec.type, metadata.tags Tags Tous transférés pour le filtrage et les overlays
User, Group Ignorés Le graphe des personnes n'est pas un concept C4

Les Components et Resources sans spec.system sont placés dans un système synthétique Uncategorized afin que rien ne soit silencieusement supprimé.

Les deux détails qui comptent le plus en pratique :

  • Les contrats d'API arrivent avec leur contenu. Chaque entité Backstage API qui inclut une spec.definition (votre YAML OpenAPI inline, votre .proto gRPC) est importée comme un Contrat d'API Archyl avec la spec complète attachée et liée au composant provider. Plus besoin de réuploader les specs à la main.
  • Les types de Resource sont préservés. Un topic Kafka ne devient pas un « service » générique — c'est un conteneur message_queue. Une instance RDS est une database. Un bucket S3 est file_storage. Votre modèle visuel reflète la nature réelle de chaque élément d'infrastructure.

Un mot sur la prolifération de ressources

Si votre organisation tourne fortement sur Kubernetes, votre catalogue Backstage contient probablement des centaines — voire des milliers — de ressources external-secret, repository, datadog-service et load-balancer auto-découvertes depuis les clusters. Nous les importons toutes.

Cela peut sembler beaucoup au premier abord. C'est le cas.

Mais vous avez plusieurs options :

  • Conservez-les et filtrez. Chaque conteneur importé porte un tag type:external-secret (ou autre). Les overlays et filtres de tags d'Archyl vous permettent de les masquer dans le diagramme tout en gardant la possibilité de les requêter.
  • Supprimez en bloc ce qui est du bruit. Deux clics par type pour retirer une catégorie entière si vous ne la voulez pas dans votre modèle.
  • Réexportez avec un filtre. Utilisez les paramètres ?filter= de Backstage pour exclure les types de ressources qui ne vous intéressent pas avant l'import.

Nous avons choisi de tout importer parce que l'alternative — supprimer silencieusement des données qu'on pensait inutiles — est pire. Vous avez curé votre catalogue. Vous décidez de ce qui reste.

Ce que vous gagnez vraiment

Un catalogue Backstage vous dit ce qui existe. Une architecture Archyl vous dit ce qui se passe.

Une fois votre catalogue dans Archyl, vous débloquez des choses que Backstage ne fait tout simplement pas :

Un véritable diagramme C4. Interactif, zoomable, navigable sur les quatre niveaux — Contexte Système, Conteneur, Composant et Code. Cliquez sur n'importe quel service pour explorer ses internals. Suivez une relation à travers la stack.

Détection de dérive. Archyl compare en continu votre architecture documentée au code réel de vos repositories. Quand votre catalogue dit « le Service A appelle le Service B » mais que le code a cessé de le faire il y a six mois, vous le découvrez — au lieu de le découvrir lors d'un incident.

Règles de conformité d'architecture. Codifiez « aucun service en dehors du domaine paiement ne peut appeler legacy-auth-api », ou « tous les appels externes doivent passer par l'API gateway ». Archyl les applique automatiquement et fait remonter les violations sur chaque PR.

Intelligence des contrats d'API. Les specs OpenAPI que vous avez alimentées dans Backstage vivent maintenant à l'intérieur de l'architecture, liées aux producteurs et consommateurs. Breaking change dans news-api ? Voyez exactement quels services aval en dépendent.

Métriques DORA liées à l'architecture. Connectez la fréquence de déploiement, le lead time, le taux d'échec des changements et le MTTR à des systèmes, conteneurs et équipes spécifiques. Voyez quelles parties de votre architecture sont saines et lesquelles sont en difficulté.

Architecture Decision Records. Ayez enfin un endroit pour écrire le pourquoi à côté du quoi, lié directement aux systèmes et composants concernés.

Intégration MCP. Chaque agent de codage IA de votre équipe — Claude Code, Cursor, Windsurf — partage le même contexte d'architecture. Arrêtez de réexpliquer comment vos services s'imbriquent à votre LLM.

Le catalogue Backstage répond à « quels services tournons-nous ? ». Archyl répond à « comment sont-ils connectés, qu'est-ce qui dérive, qu'est-ce qui est à risque, et où devrions-nous investir ? ». Importer votre catalogue signifie que vous n'avez pas à choisir entre les deux.

Pour les workflows d'agents IA

Le même import est exposé via le serveur MCP d'Archyl. Pointez Claude Code, Cursor ou n'importe quel agent de codage IA vers l'outil import_dsl avec format: "backstage" et le contenu de votre entities.json — votre architecture atterrit sans que personne ne touche à un navigateur.

Utilisez l'outil import_dsl avec :
- projectId: <UUID de votre projet>
- content: <contenu de entities.json>
- format: "backstage"

Utile quand vous scriptez des syncs de catalogue depuis CI, ou quand vous voulez que votre assistant IA rafraîchisse le modèle après une mise à jour majeure de Backstage.

Essayez maintenant

Si votre équipe utilise Backstage aujourd'hui, vous êtes littéralement à un curl d'une architecture C4 complète.

  1. Lancez le curl ci-dessus.
  2. Ouvrez Archyl, cliquez sur Importer un projet, choisissez Backstage.
  3. Regardez vos services, APIs, queues et bases de données s'organiser en une architecture navigable.

L'import fonctionne sur tous les plans, y compris la version gratuite. Nous ne pensons pas que votre décision devrait dépendre de la portabilité de votre catalogue — elle devrait dépendre de ce que vous voulez en faire ensuite.

Votre catalogue Backstage attend depuis longtemps de devenir une architecture. Allez la lui offrir.