Importare un catalogo Backstage in Archyl: Backstage verso C4

Trasforma il tuo Software Catalog Backstage in un modello C4 navigabile. System, Component, Resource e spec API inline arrivano da entities.json.

Importazione Backstage

Importa il tuo catalogo Backstage in Archyl

Backstage elenca ciò che hai in produzione. Archyl trasforma lo stesso catalogo in un modello C4 navigabile: i System diventano sistemi, i Component e le Resource diventano container, e ogni entità API diventa un contratto con la sua spec conservata inalterata e collegata ai servizi che la forniscono e la consumano. Tieni Backstage. La proprietà non viene trasferita, e ottieni due livelli C4 su cui costruire.

Importare un catalogo Backstage in Archyl | Backstage verso C4

Trasforma il tuo Software Catalog Backstage in un modello di architettura C4 navigabile. System, Component, Resource e spec API inline vengono importati da entities.json. La proprietà resta in Backstage.

Backstage verso C4, importare catalogo Backstage, esportare catalogo Backstage, diagramma architettura Backstage, modello C4 Backstage software catalog, documentazione architettura Backstage

Ogni entità System diventa un sistema software C4 con la sua descrizione e i suoi tag. Due System con lo stesso nome in namespace diversi vengono rinominati anziché fusi, e l'importazione ti dice quali.

I Component diventano container sotto il System a cui appartengono, risolto da spec.system o da una relazione partOf. Il loro spec.type viene mappato: service verso servizio, website verso applicazione web, cronworkflow verso worker, library verso libreria.

Anche le Resource diventano container, tipizzate a partire da spec.type. Le istanze RDS e i cluster Valkey diventano database, i topic Kafka e le code SQS diventano code di messaggi, i bucket S3 diventano storage di file.

Le entità API diventano contratti API di Archyl. Lo spec.definition inline viene conservato alla lettera, tipizzato come HTTP, gRPC, GraphQL o async, e collegato ai container che lo forniscono e lo consumano.

dependsOn, consumesApi, producesTo, consumesFrom e versionedIn diventano relazioni tipizzate. Backstage emette la maggior parte delle relations in entrambe le direzioni e l'importazione ne conserva una. Un arco consumesApi viene risolto attraverso l'API fino al container che la fornisce davvero.

Namespace e lifecycle

I tuoi metadata.tags arrivano invariati, insieme a namespace, lifecycle e type come tag con prefisso, così il raggruppamento che hai curato in Backstage sopravvive nel modello di architettura.

Chiama l'API catalog del tuo Backstage e salva la risposta. L'endpoint entities restituisce ogni System, Component, Resource e API che conosce come un unico array JSON.

Scegli il formato Backstage

Nella finestra di importazione di Archyl, scegli la scheda "Backstage". Accetta l'array entities esattamente come lo esporta Backstage, senza rimaneggiarlo.

Carica o incolla entities.json

Carica il file o incollalo, poi valida. Archyl segnala ogni errore nel JSON prima che tu confermi l'importazione.

Importa, poi leggi gli avvisi

Archyl costruisce il modello e riporta quanti sistemi, container, contratti API e relazioni ha creato, oltre a ogni entità che ha dovuto rinominare. Assegna i proprietari dopo: Group e User di Backstage non vengono importati.

Rilevamento della deriva

Ottieni un punteggio di salute 0-100% che mostra quanto la tua documentazione riflette il tuo codice sorgente. Rileva la deriva prima che si accumuli.

Definisci regole architetturali ed esegui verifiche automatizzate per garantire che il tuo sistema rimanga entro i limiti definiti.

Monitora la frequenza di deployment, il tempo di consegna, il tasso di errore e il tempo di recupero insieme alla salute della tua architettura.

Server MCP (181 strumenti)

Interroga i dati architetturali da Claude, Cursor o Windsurf attraverso 181 strumenti MCP specializzati.

Architecture Decision Records

Collega gli ADR direttamente agli elementi C4 affinché ogni decisione di progettazione abbia un contesto tracciabile.

Allega schemi OpenAPI, AsyncAPI o GraphQL a container e componenti. Mantieni i contratti versionati con la tua architettura.

Dobbiamo abbandonare Backstage?

No, e la maggior parte dei team non dovrebbe. Backstage è un portale per sviluppatori; Archyl è un modello di architettura. L'importazione legge un export del catalogo e non tocca mai la tua istanza Backstage, quindi entrambi continuano a funzionare. Archyl risponde alle domande a cui un catalogo piatto non può rispondere: come si incastrano questi servizi, cosa è derivato rispetto al codice e quali contratti si rompono se uno di essi cambia.

Quanti livelli C4 mi dà l'importazione?

Due. I System arrivano al livello 1 del C4, e sia i Component sia le Resource arrivano al livello 2 come container. Backstage non ha alcun kind di entità sotto Component, quindi non c'è nulla con cui riempire il livello 3. Componenti ed elementi di codice li aggiungi dopo a mano, oppure punti la scoperta IA di Archyl sul repository e approvi ciò che propone.

La proprietà viene trasferita?

No. Le entità User e Group vengono saltate e le relations ownedBy non vengono mappate, quindi spec.owner non diventa un proprietario in Archyl. È l'unica cosa da pianificare: se usi la mappa di proprietà di Archyl, assegni i proprietari dopo l'importazione.

Che fine fanno le nostre spec OpenAPI e gRPC?

Un'entità API che porta uno spec.definition inline conserva quella spec alla lettera come contratto API di Archyl, tipizzata da spec.type come HTTP, gRPC, GraphQL o async, e collegata ai container che la forniscono e la consumano. Un'entità API senza definizione inline arriva comunque con nome, descrizione e tipo, ma senza corpo.

Cosa salta l'importazione?

Le entità User e Group, insieme alle relations ownedBy che puntano a esse. Le entità Location e Template. I blocchi metadata.annotations e metadata.links, il che significa che il puntatore a TechDocs non arriva. Le relations fuori dall'insieme mappato vengono ignorate. L'importazione ti avvisa delle entità duplicate e rinominate. I kind qui sopra vengono scartati senza avviso, ed è per questo che questa pagina li nomina.

Il nostro catalogo ha migliaia di Resource scoperte automaticamente. Entrano tutte?