Importar um catalogo do Backstage no Archyl: Backstage para C4

Transforme seu Software Catalog do Backstage em um modelo C4 navegavel. System, Component, Resource e specs de API inline vem do entities.json.

Importação do Backstage

Importe seu catálogo do Backstage para o Archyl

O Backstage lista o que você executa. O Archyl transforma esse mesmo catálogo em um modelo C4 navegável: os System viram sistemas, os Component e os Resource viram containers, e cada entidade API vira um contrato com sua spec preservada tal como está e ligada aos serviços que a fornecem e a consomem. Você mantém o Backstage. A propriedade não é transferida, e você fica com dois níveis C4 para construir em cima.

Importar um catálogo do Backstage no Archyl | Backstage para C4

Transforme seu Software Catalog do Backstage em um modelo de arquitetura C4 navegável. System, Component, Resource e specs de API inline são importados do entities.json. A propriedade fica no Backstage.

Backstage para C4, importar catálogo Backstage, exportar catálogo Backstage, diagrama de arquitetura Backstage, modelo C4 Backstage software catalog, documentação de arquitetura Backstage

Cada entidade System vira um sistema de software C4 com sua descrição e suas tags. Dois System com o mesmo nome em namespaces diferentes são renomeados em vez de mesclados, e a importação avisa quais.

Os Component viram containers sob o System a que pertencem, resolvido a partir de spec.system ou de uma relação partOf. O spec.type deles é mapeado: service para serviço, website para aplicação web, cronworkflow para worker, library para biblioteca.

Os Resource também viram containers, tipados a partir de spec.type. Instâncias RDS e clusters Valkey viram bancos de dados, tópicos Kafka e filas SQS viram filas de mensagens, buckets S3 viram armazenamento de arquivos.

As entidades API viram contratos de API do Archyl. O spec.definition inline é mantido literalmente, tipado como HTTP, gRPC, GraphQL ou async, e ligado aos containers que o fornecem e o consomem.

dependsOn, consumesApi, producesTo, consumesFrom e versionedIn viram relacionamentos tipados. O Backstage emite a maioria das relations nos dois sentidos e a importação mantém uma. Uma aresta consumesApi é resolvida através da API até o container que realmente a fornece.

Namespaces e lifecycle

Suas metadata.tags chegam sem alteração, ao lado de namespace, lifecycle e type como tags prefixadas, para que o agrupamento que você organizou no Backstage sobreviva no modelo de arquitetura.

Chame a API catalog do seu Backstage e salve a resposta. O endpoint entities devolve cada System, Component, Resource e API que ele conhece como um único array JSON.

Escolha o formato Backstage

No diálogo de importação do Archyl, escolha a aba "Backstage". Ela aceita o array entities exatamente como o Backstage o exporta, sem remodelagem.

Faça upload ou cole o entities.json

Faça upload do arquivo ou cole o conteúdo e depois valide. O Archyl aponta qualquer erro no JSON antes de você confirmar a importação.

Importe e leia os avisos

O Archyl constrói o modelo e informa quantos sistemas, containers, contratos de API e relacionamentos criou, além de cada entidade que precisou renomear. Atribua os proprietários depois: Groups e Users do Backstage não são importados.

Obtenha uma pontuação de saúde de 0-100% mostrando a fidelidade da sua documentação em relação ao seu código-fonte. Detecte desvios antes que se acumulem.

Regras de conformidade

Defina regras de arquitetura e execute verificações automatizadas para garantir que seu sistema permaneça dentro dos limites definidos.

Acompanhe a frequência de deploy, tempo de entrega, taxa de falhas e tempo de recuperação junto com a saúde da sua arquitetura.

Servidor MCP (181 ferramentas)

Consulte dados de arquitetura a partir do Claude, Cursor ou Windsurf por meio de 181 ferramentas MCP especializadas.

Architecture Decision Records

Vincule ADRs diretamente aos elementos C4 para que cada decisão de design tenha contexto rastreável.

Anexe schemas OpenAPI, AsyncAPI ou GraphQL a containers e componentes. Mantenha contratos versionados com sua arquitetura.

Precisamos abandonar o Backstage?

Não, e a maioria das equipes não deveria. O Backstage é um portal de desenvolvedores; o Archyl é um modelo de arquitetura. A importação lê um export do catálogo e nunca toca na sua instância do Backstage, então os dois continuam rodando. O Archyl responde às perguntas que um catálogo plano não consegue: como esses serviços se encaixam, o que desviou do código e quais contratos quebram se um deles mudar.

Quantos níveis C4 a importação me dá?

Dois. Os System chegam no nível 1 do C4, e tanto Component quanto Resource chegam no nível 2 como containers. O Backstage não tem nenhum kind de entidade abaixo de Component, então não há nada para preencher o nível 3. Você adiciona componentes e elementos de código depois, à mão, ou aponta a descoberta por IA do Archyl para o repositório e aprova o que ela propõe.

A propriedade é transferida?

Não. As entidades User e Group são ignoradas e as relations ownedBy não são mapeadas, então spec.owner não vira um proprietário no Archyl. Esse é o único ponto que vale planejar: se você usa o mapa de propriedade do Archyl, atribui os proprietários depois da importação.

O que acontece com nossas specs OpenAPI e gRPC?

Uma entidade API que carrega um spec.definition inline mantém essa spec literalmente como contrato de API do Archyl, tipada a partir de spec.type como HTTP, gRPC, GraphQL ou async, e ligada aos containers que a fornecem e a consomem. Uma entidade API sem definição inline ainda chega com nome, descrição e tipo, mas sem corpo.

O que a importação ignora?

As entidades User e Group, junto com as relations ownedBy que apontam para elas. As entidades Location e Template. Os blocos metadata.annotations e metadata.links, o que significa que o ponteiro do TechDocs não vem junto. Relations fora do conjunto mapeado são ignoradas. A importação avisa sobre entidades duplicadas e renomeadas. Os kinds acima são descartados sem aviso, e é por isso que esta página os nomeia.

Nosso catálogo tem milhares de Resource descobertos automaticamente. Todos entram?