Transforme seu catálogo Backstage em uma arquitetura C4 real em 60 segundos

Backstage é o catálogo. Se você trabalha em um time de plataforma, é provável que tenha passado meses curando arquivos catalog-info.yaml, configurando anotações, ajustando links dependsOn e respondendo perguntas no Slack sobre por que um serviço não aparece. Esse trabalho é real. Representa um mapa concreto dos seus sistemas.

Mas aqui está o ponto: o Backstage foi construído para listar seu software, não para modelá-lo. As páginas de componentes são úteis. As relações são esparsas. O plugin C4 é um adendo. Você pode rolar por 700 serviços em uma lista plana, mas não consegue ver como eles se encaixam.

Se você queria uma visão arquitetural real, normalmente tinha uma escolha: reconstruir seu catálogo manualmente em outra ferramenta, ou conviver com o que o Backstage oferece.

Hoje, essa escolha desaparece.

O Archyl agora importa seu Software Catalog do Backstage diretamente. Um curl, um upload, e cada System, Component, Resource e API que você já curou aparece como um modelo C4 completo e navegável — com relações, contratos OpenAPI, recursos de infraestrutura e metadados intactos.

Sessenta segundos, três passos

O Backstage expõe seu catálogo completo de entidades por meio de um único endpoint REST. Puxe-o, jogue-o no Archyl, pronto.

Passo 1 — Exporte seu catálogo

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

Esse é o export inteiro. O endpoint transmite todas as entidades que o Backstage conhece: Systems, Components, Resources, APIs, Groups, Users — tudo. Para a maioria das organizações, você obtém um array JSON de 5–30 MB com milhares de entradas.

Se você está testando sem auth (algumas instâncias do Backstage permitem leituras públicas do catálogo na rede interna), pode tirar o header Authorization. Se precisar filtrar por kind para manter o arquivo menor, o Backstage suporta query params: ?filter=kind=component,kind=system,kind=api,kind=resource reduzirá a resposta apenas ao que o Archyl realmente mapeia.

Passo 2 — Abra o diálogo de import

No Archyl, clique em Importar Projeto (ou Importar dentro de um projeto existente), selecione a aba Backstage e faça upload do entities.json ou cole-o diretamente.

O Archyl valida o arquivo e então mostra exatamente o que será criado — número de sistemas, contêineres, contratos de API, relações — antes de qualquer coisa ser escrita.

Passo 3 — Clique em importar

Seu projeto é populado. Um catálogo de 9 MB com ~3.000 entidades importa em segundos. Você pode agora clicar em qualquer sistema, ver seus contêineres dispostos no nível C4 Level 2, mergulhar nas APIs e seguir as arestas dependsOn através do seu stack.

O que realmente é mapeado

A parte difícil do import a partir do Backstage não é ler o JSON — é traduzir entre dois modelos mentais diferentes. O Backstage pensa em entidades planas conectadas por relações tipadas. O C4 pensa em níveis aninhados. Veja como o Archyl faz a ponte:

Backstage Archyl Notas
System C4 System (Nível 1) Sistemas com o mesmo nome em namespaces diferentes são auto-desambiguados
Component Container sob seu System proprietário service → service, cronworkflow → worker, website → web_app
Resource Container sob seu System proprietário Sensível ao tipo: s3-bucket → file_storage; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database; kafka-topic, sqs-queue → message_queue; repository → library
API (com spec.definition) Contrato de API Specs OpenAPI 3, gRPC, GraphQL, AsyncAPI são preservadas inline e ligadas aos componentes provedores/consumidores
dependsOn, dependencyOf Relação depends_on Pares bidirecionais são deduplicados automaticamente
consumesApi Relação uses Resolvida através da API até seu componente provedor real
producesTo, producedBy Relação publishes_to
consumesFrom, consumedBy Relação consumes_from
versionedIn, versions Relação depends_on Etiquetada como "source code"
metadata.namespace, spec.lifecycle, spec.type, metadata.tags Tags Todos transferidos para filtragem e overlays
User, Group Ignorados O grafo de pessoas não é um conceito C4

Components e Resources sem spec.system vão para um sistema sintético chamado Uncategorized para que nada seja silenciosamente descartado.

Os dois detalhes que mais importam na prática:

  • Os contratos de API vêm com seu conteúdo. Cada entidade API do Backstage que inclui uma spec.definition (seu YAML OpenAPI inline, seu .proto gRPC) é importada como um Contrato de API do Archyl com a spec completa anexada e ligada ao componente provedor. Sem reuploads manuais de specs.
  • Os tipos de Resource são preservados. Um topic Kafka não vira um "service" genérico — é um container message_queue. Uma instância RDS é um database. Um bucket S3 é file_storage. Seu modelo visual reflete a natureza real de cada peça de infraestrutura.

Uma palavra sobre proliferação de recursos

Se sua organização roda fortemente em Kubernetes, seu catálogo Backstage provavelmente tem centenas — talvez milhares — de recursos external-secret, repository, datadog-service e load-balancer auto-descobertos a partir dos clusters. Importamos todos.

À primeira vista pode parecer muito. É.

Mas você tem várias opções:

  • Mantenha-os e filtre. Todo container importado carrega uma tag type:external-secret (ou similar). Os overlays e filtros de tag do Archyl permitem ocultá-los no diagrama enquanto continuam consultáveis.
  • Apague em massa o que é ruído. Dois cliques por tipo para remover uma categoria inteira se você não a quer no seu modelo.
  • Re-exporte com um filtro. Use os query params ?filter= do Backstage para excluir tipos de recurso que não te interessam antes do import.

Escolhemos importar tudo porque a alternativa — descartar silenciosamente dados que achamos que você não precisava — é pior. Você curou seu catálogo. Você decide o que fica.

O que você realmente ganha

Um catálogo Backstage te diz o que existe. Uma arquitetura Archyl te diz o que está acontecendo.

Uma vez que seu catálogo vive no Archyl, você desbloqueia coisas que o Backstage simplesmente não faz:

Um diagrama C4 real. Interativo, com zoom, navegável pelos quatro níveis — System Context, Container, Component e Code. Clique em qualquer serviço para mergulhar em seus internals. Siga uma relação através do stack.

Detecção de drift. O Archyl compara continuamente sua arquitetura documentada com o código real nos seus repositórios. Quando seu catálogo diz "o Serviço A chama o Serviço B" mas o código parou de fazer isso seis meses atrás, você descobre — em vez de descobrir durante um incidente.

Regras de conformidade arquitetural. Codifique "nenhum serviço fora do domínio de pagamentos pode chamar legacy-auth-api", ou "todas as chamadas externas devem passar pelo API gateway". O Archyl as aplica automaticamente e expõe violações em cada PR.

Inteligência de contratos de API. As specs OpenAPI que você alimentou no Backstage agora vivem dentro da arquitetura, ligadas a produtores e consumidores. Breaking change em news-api? Veja exatamente quais serviços downstream dependem dela.

Métricas DORA atreladas à arquitetura. Conecte frequência de deploy, lead time, taxa de falha em mudanças e MTTR a sistemas, contêineres e times específicos. Veja quais partes da sua arquitetura estão saudáveis e quais estão em apuros.

Architecture Decision Records. Finalmente tenha um lugar para escrever o porquê ao lado do quê, ligado diretamente aos sistemas e componentes afetados.

Integração MCP. Cada agente de coding IA no seu time — Claude Code, Cursor, Windsurf — compartilha o mesmo contexto arquitetural. Pare de re-explicar para seu LLM como seus serviços se encaixam.

O catálogo Backstage responde "quais serviços rodamos?". O Archyl responde "como estão conectados, o que está derivando, o que está em risco e onde devemos investir?". Importar seu catálogo significa que você não precisa escolher entre os dois.

Para fluxos de trabalho de agentes IA

O mesmo import está exposto através do servidor MCP do Archyl. Aponte Claude Code, Cursor ou qualquer agente de coding IA para a ferramenta import_dsl com format: "backstage" e o conteúdo do seu entities.json — e sua arquitetura cai sem ninguém tocar um navegador.

Use a ferramenta import_dsl com:
- projectId: <UUID do seu projeto>
- content: <conteúdo de entities.json>
- format: "backstage"

Útil quando você está scriptando syncs de catálogo a partir do CI, ou quando quer que seu assistente IA atualize o modelo após uma atualização maior do Backstage.

Experimente agora

Se seu time roda Backstage hoje, você está literalmente a um curl de uma arquitetura C4 completa.

  1. Execute o curl acima.
  2. Abra o Archyl, clique em Importar Projeto, escolha Backstage.
  3. Veja seus serviços, APIs, filas e bancos de dados se encaixarem em uma arquitetura navegável.

O import funciona em todos os planos, incluindo o tier gratuito. Não achamos que sua decisão deva depender de o seu catálogo ser portável — deveria depender do que você quer fazer com ele em seguida.

Seu catálogo Backstage estava esperando para se tornar uma arquitetura. Vá fazê-la acontecer.