Importer un catalogue Backstage dans Archyl: Backstage vers C4

Transformez votre Software Catalog Backstage en modele C4 navigable. System, Component, Resource et specs API inline sont importes depuis entities.json.

Importez votre catalogue Backstage dans Archyl

Backstage liste ce que vous exploitez. Archyl transforme ce même catalogue en un modèle C4 navigable : les System deviennent des systèmes, les Component et les Resource deviennent des containers, et chaque entité API devient un contrat dont la spec est conservée telle quelle et reliée aux services qui la fournissent et la consomment. Vous gardez Backstage. La propriété n'est pas importée, et vous obtenez deux niveaux C4 sur lesquels construire.

Importer un catalogue Backstage dans Archyl | Backstage vers C4

Transformez votre Software Catalog Backstage en un modèle C4 navigable. Les System, Component, Resource et les specs API inline sont importés depuis entities.json. La propriété reste dans Backstage.

Backstage vers C4, import catalogue Backstage, exporter catalogue Backstage, diagramme architecture Backstage, modèle C4 Backstage software catalog, documentation architecture Backstage

Chaque entité System devient un système logiciel C4 avec sa description et ses tags. Deux System portant le même nom dans des namespaces différents sont renommés plutôt que fusionnés, et l'import vous indique lesquels.

Les Component deviennent des containers sous le System qui les possède, résolu depuis spec.system ou une relation partOf. Leur spec.type est mappé : service vers service, website vers application web, cronworkflow vers worker, library vers librairie.

Les Resource deviennent aussi des containers, types depuis spec.type. Les instances RDS et les clusters Valkey deviennent des bases de données, les topics Kafka et les files SQS deviennent des files de messages, les buckets S3 deviennent du stockage de fichiers.

Les entités API deviennent des contrats d'API Archyl. Le spec.définition inline est conservé mot pour mot, type en HTTP, gRPC, GraphQL ou async, et relié aux containers qui le fournissent et le consomment.

dependsOn, consumesApi, producesTo, consumesFrom et versionedIn deviennent des relations typées. Backstage émet la plupart des relations dans les deux sens et l'import n'en garde qu'une. Un lien consumesApi est résolu à travers l'API jusqu'au container qui la fournit réellement.

Namespaces et lifecycle

Vos metadata.tags arrivent tels quels, aux côtés de namespace, lifecycle et type sous forme de tags préfixés, pour que le regroupement que vous avez soigné dans Backstage survive dans le modèle d'architecture.

Exportez le catalogue

Appelez l'API catalog de votre Backstage et sauvegardez la réponse. L'endpoint entities renvoie chaque System, Component, Resource et API qu'il connaît sous forme d'un unique tableau JSON.

Choisissez le format Backstage

Dans le dialogue d'import d'Archyl, choisissez l'onglet "Backstage". Il accepte le tableau entities exactement tel que Backstage l'exporte, sans remise en forme.

Uploadez ou collez entities.json

Uploadez le fichier ou collez-le, puis validez. Archyl signale les erreurs du JSON avant que vous ne lanciez l'import.

Importez, puis lisez les avertissements

Archyl construit le modèle et indique combien de systèmes, containers, contrats d'API et relations il a créés, ainsi que chaque entité qu'il a dû renommer. Assignez les propriétaires ensuite : les Group et les User Backstage ne sont pas importés.

Obtenez un score de santé 0-100% montrant la fidélité de votre documentation par rapport à votre codebase. Détectez la dérive avant qu'elle ne s'accumule.

Définissez des règles d'architecture et exécutez des vérifications automatisées pour garantir que votre système reste dans les limites définies.

Suivez la fréquence de déploiement, le délai de mise en production, le taux d'échec et le temps de récupération en parallèle de la santé de votre architecture.

Serveur MCP (181 outils)

Interrogez les données d'architecture depuis Claude, Cursor ou Windsurf via 181 outils MCP spécialisés.

Architecture Decision Records

Liez les ADR directement aux éléments C4 pour que chaque décision de conception ait un contexte traçable.

Attachez des schémas OpenAPI, AsyncAPI ou GraphQL aux containers et composants. Gardez les contrats versionnés avec votre architecture.

Devons-nous quitter Backstage ?

Non, et la plupart des équipes ne devraient pas. Backstage est un portail développeur ; Archyl est un modèle d'architecture. L'import lit un export de catalogue et ne touche jamais à votre instance Backstage : les deux continuent de tourner. Archyl répond aux questions qu'un catalogue plat ne peut pas traiter : comment ces services s'articulent, ce qui a dérivé par rapport au code, et quels contrats cassent si l'un d'eux change.

Combien de niveaux C4 l'import me donne-t-il ?

Deux. Les System arrivent au niveau 1 du C4, et les Component comme les Resource arrivent au niveau 2 en tant que containers. Backstage n'a aucun kind d'entité sous Component : il n'y a donc rien pour alimenter le niveau 3. Vous ajoutez ensuite les composants et les éléments de code à la main, ou vous pointez la découverte IA d'Archyl sur le dépôt et approuvez ce qu'elle propose.

La propriété est-elle transférée ?

Non. Les entités User et Group sont ignorées et les relations ownedBy ne sont pas mappées : spec.owner ne devient donc pas un propriétaire dans Archyl. C'est le seul point à anticiper : si vous utilisez la carte de propriété d'Archyl, vous assignez les propriétaires après l'import.

Qu'advient-il de nos specs OpenAPI et gRPC ?

Une entité API portant un spec.définition inline conserve cette spec mot pour mot sous forme de contrat d'API Archyl, typée depuis spec.type en HTTP, gRPC, GraphQL ou async, et reliée aux containers qui la fournissent et la consomment. Une entité API sans définition inline est quand même importée avec son nom, sa description et son type, mais sans corps.

Qu'est-ce que l'import ignore ?

Les entités User et Group, ainsi que les relations ownedBy qui pointent vers elles. Les entités Location et Template. Les blocs metadata.annotations et metadata.links, ce qui signifie que le pointeur TechDocs n'est pas repris. Les relations hors de l'ensemble mappé sont ignorées. L'import vous avertit des entités dupliquées et renommées. Les kinds ci-dessus sont écartés sans avertissement, et c'est pour cela que cette page les nomme.

Notre catalogue contient des milliers de Resource découvertes automatiquement. Arrivent-elles toutes ?

Oui. Chaque Resource est importée, parce que supprimer en silence des données que vous avez soignées est pire qu'en importer trop. Chaque container conserve un tag de type issu de son spec.type Backstage : les catégories bruyantes restent identifiables, et vous pouvez restreindre l'import à la source avec le paramètre de requête filter de Backstage avant d'exporter.