Trasforma il tuo catalogo Backstage in una vera architettura C4 in 60 secondi

Backstage è il catalogo. Se lavori in un team di piattaforma, è probabile che tu abbia passato mesi a curare i file catalog-info.yaml, configurare le annotation, sistemare i collegamenti dependsOn e rispondere alle domande su Slack del tipo "perché un servizio non appare?". Quel lavoro è reale. Rappresenta una mappa concreta dei tuoi sistemi.

Ma ecco il punto: Backstage è stato costruito per elencare il tuo software, non per modellarlo. Le pagine dei component sono utili. Le relazioni sono scarse. Il plugin C4 è un ripensamento. Puoi scorrere 700 servizi in una lista piatta, ma non puoi vedere come si incastrano tra loro.

Se volevi una vera vista architetturale, di solito avevi una scelta: ricostruire il catalogo a mano in un altro tool, o convivere con quello che Backstage offre.

Oggi quella scelta scompare.

Archyl ora importa direttamente il tuo Software Catalog Backstage. Un curl, un upload, e ogni System, Component, Resource e API che hai già curato appare come un modello C4 completo e navigabile — con relazioni, contratti OpenAPI, risorse infrastrutturali e metadati intatti.

Sessanta secondi, tre passi

Backstage espone il suo catalogo completo di entità tramite un singolo endpoint REST. Recuperalo, trascinalo in Archyl, fatto.

Passo 1 — Esporta il tuo catalogo

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

Questo è l'intero export. L'endpoint trasmette ogni entità che Backstage conosce: Systems, Components, Resources, APIs, Groups, Users — tutto. Per la maggior parte delle organizzazioni, ottieni un array JSON da 5–30 MB con migliaia di voci.

Se stai testando senza autenticazione (alcune istanze Backstage permettono letture pubbliche del catalogo sulla rete interna), puoi rimuovere l'header Authorization. Se hai bisogno di filtrare per kind per mantenere il file più piccolo, Backstage supporta query param: ?filter=kind=component,kind=system,kind=api,kind=resource ridurrà la risposta solo a ciò che Archyl effettivamente mappa.

Passo 2 — Apri il dialogo di import

In Archyl, clicca su Importa Progetto (o Importa all'interno di un progetto esistente), seleziona la scheda Backstage e carica entities.json o incollalo direttamente.

Archyl valida il file, poi ti mostra esattamente cosa verrà creato — numero di sistemi, container, contratti API, relazioni — prima che venga scritto qualcosa.

Passo 3 — Clicca su importa

Il tuo progetto si popola. Un catalogo da 9 MB con ~3.000 entità si importa in pochi secondi. Ora puoi cliccare su qualsiasi sistema, vedere i suoi container disposti a livello C4 Level 2, addentrarti nelle API e seguire i collegamenti dependsOn attraverso il tuo stack.

Cosa viene effettivamente mappato

La parte difficile dell'import da Backstage non è leggere il JSON — è tradurre tra due modelli mentali diversi. Backstage pensa in entità piatte connesse da relazioni tipizzate. C4 pensa in livelli annidati. Ecco come Archyl fa da ponte:

Backstage	Archyl	Note
`System`	C4 System (Livello 1)	I sistemi con lo stesso nome in namespace diversi vengono auto-disambiguati
`Component`	Container sotto il System di appartenenza	`service` → service, `cronworkflow` → worker, `website` → web_app
`Resource`	Container sotto il System di appartenenza	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` (con `spec.definition`)	Contratto API	Le specifiche OpenAPI 3, gRPC, GraphQL, AsyncAPI vengono preservate inline e collegate ai componenti provider/consumer
`dependsOn`, `dependencyOf`	Relazione `depends_on`	Le coppie bidirezionali vengono deduplicate automaticamente
`consumesApi`	Relazione `uses`	Risolta attraverso l'API fino al suo componente provider effettivo
`producesTo`, `producedBy`	Relazione `publishes_to`
`consumesFrom`, `consumedBy`	Relazione `consumes_from`
`versionedIn`, `versions`	Relazione `depends_on`	Etichettata "source code"
`metadata.namespace`, `spec.lifecycle`, `spec.type`, `metadata.tags`	Tags	Tutti trasferiti per filtraggio e overlay
`User`, `Group`	Saltati	Il grafo delle persone non è un concetto C4

I Component e Resource senza spec.system finiscono in un sistema sintetico chiamato Uncategorized in modo che nulla venga scartato silenziosamente.

I due dettagli che contano di più nella pratica:

I contratti API arrivano con il loro contenuto. Ogni entità Backstage API che include una spec.definition (il tuo YAML OpenAPI inline, il tuo .proto gRPC) viene importata come un Contratto API Archyl con la spec completa allegata e collegata al componente provider. Niente più caricamenti manuali di specifiche.
I tipi di Resource sono preservati. Un topic Kafka non diventa un generico "service" — è un container message_queue. Un'istanza RDS è un database. Un bucket S3 è file_storage. Il tuo modello visivo riflette la natura reale di ogni pezzo di infrastruttura.

Una parola sulla proliferazione di risorse

Se la tua organizzazione gira pesantemente su Kubernetes, il tuo catalogo Backstage probabilmente ha centinaia — forse migliaia — di risorse external-secret, repository, datadog-service e load-balancer auto-rilevate dai cluster. Le importiamo tutte.

A prima vista può sembrare tanto. E lo è.

Ma hai diverse opzioni:

Tienile e filtra. Ogni container importato porta un tag type:external-secret (o quello che è). Gli overlay e i filtri tag di Archyl ti permettono di nasconderli nel diagramma pur mantenendoli interrogabili.
Cancella in massa il rumore. Due clic per tipo per rimuovere un'intera categoria se non la vuoi nel tuo modello.
Riesporta con un filtro. Usa i query param ?filter= di Backstage per escludere i kind di risorse che non ti interessano prima dell'import.

Abbiamo scelto di importare tutto perché l'alternativa — scartare silenziosamente dati che pensavamo non ti servissero — è peggio. Tu hai curato il tuo catalogo. Tu decidi cosa rimane.

Cosa guadagni davvero

Un catalogo Backstage ti dice cosa esiste. Un'architettura Archyl ti dice cosa sta succedendo.

Una volta che il tuo catalogo vive in Archyl, sblocchi cose che Backstage semplicemente non fa:

Un vero diagramma C4. Interattivo, zoomabile, navigabile attraverso tutti e quattro i livelli — System Context, Container, Component e Code. Clicca su qualsiasi servizio per addentrarti nei suoi internal. Segui una relazione attraverso lo stack.

Rilevamento del drift. Archyl confronta continuamente la tua architettura documentata con il codice reale nei tuoi repository. Quando il tuo catalogo dice "il Servizio A chiama il Servizio B" ma il codice ha smesso di farlo sei mesi fa, lo scopri — invece di scoprirlo durante un incidente.

Regole di conformità architetturale. Codifica "nessun servizio al di fuori del dominio pagamenti può chiamare legacy-auth-api", oppure "tutte le chiamate esterne devono passare attraverso l'API gateway". Archyl le applica automaticamente e fa emergere le violazioni su ogni PR.

Intelligenza dei contratti API. Le specifiche OpenAPI che hai alimentato in Backstage ora vivono dentro l'architettura, collegate a producer e consumer. Breaking change in news-api? Vedi esattamente quali servizi a valle dipendono da essa.

Metriche DORA legate all'architettura. Collega frequenza di deploy, lead time, tasso di fallimento dei cambiamenti e MTTR a sistemi, container e team specifici. Vedi quali parti della tua architettura sono in salute e quali sono in difficoltà.

Architecture Decision Records. Finalmente avrai un posto dove scrivere il perché accanto al cosa, collegato direttamente ai sistemi e componenti coinvolti.

Integrazione MCP. Ogni agente di coding AI nel tuo team — Claude Code, Cursor, Windsurf — condivide lo stesso contesto architetturale. Smetti di rispiegare al tuo LLM come si incastrano i tuoi servizi.

Il catalogo Backstage risponde a "quali servizi facciamo girare?". Archyl risponde a "come sono connessi, cosa sta derivando, cosa è a rischio e dove dovremmo investire?". Importare il tuo catalogo significa che non devi scegliere tra i due.

Per i workflow di agenti AI

Lo stesso import è esposto tramite il server MCP di Archyl. Punta Claude Code, Cursor o qualsiasi agente di coding AI al tool import_dsl con format: "backstage" e il contenuto del tuo entities.json — e la tua architettura atterra senza che nessuno tocchi un browser.

Usa il tool import_dsl con:
- projectId: <UUID del tuo progetto>
- content: <contenuto di entities.json>
- format: "backstage"

Utile quando scripting sync di catalogo dalla CI, o quando vuoi che il tuo assistente AI aggiorni il modello dopo un major update di Backstage.

Provalo ora

Se il tuo team usa Backstage oggi, sei letteralmente a un curl di distanza da un'architettura C4 completa.

Esegui il curl qui sopra.
Apri Archyl, clicca su Importa Progetto, scegli Backstage.
Guarda i tuoi servizi, API, queue e database incastrarsi in un'architettura navigabile.

L'import funziona su tutti i piani, incluso il tier gratuito. Non pensiamo che la tua decisione debba dipendere dalla portabilità del tuo catalogo — dovrebbe dipendere da cosa vuoi farci dopo.

Il tuo catalogo Backstage aspettava da tempo di diventare un'architettura. Vai a renderla tale.