Convierte tu catálogo de Backstage en una arquitectura C4 real en 60 segundos

Backstage es el catálogo. Si trabajas en un equipo de plataforma, lo más probable es que hayas pasado meses curando archivos catalog-info.yaml, configurando anotaciones, ajustando enlaces dependsOn y respondiendo preguntas en Slack sobre por qué un servicio no aparece. Ese trabajo es real. Representa un mapa real de tus sistemas.

Pero aquí está el detalle: Backstage fue construido para listar tu software, no para modelarlo. Las páginas de componentes son útiles. Las relaciones son escasas. El plugin de C4 es algo añadido. Puedes recorrer 700 servicios en una lista plana, pero no puedes ver cómo encajan entre sí.

Si querías una vista de arquitectura real, normalmente tenías una elección: reconstruir tu catálogo a mano en otra herramienta, o convivir con lo que Backstage ofrece.

Hoy, esa elección desaparece.

Archyl ahora importa tu Software Catalog de Backstage directamente. Un curl, una carga, y cada System, Component, Resource y API que ya has curado aparece como un modelo C4 completo y navegable — con relaciones, contratos OpenAPI, recursos de infraestructura y metadatos intactos.

Sesenta segundos, tres pasos

Backstage expone su catálogo de entidades completo a través de un único endpoint REST. Tíralo, suéltalo en Archyl, listo.

Paso 1 — Exporta tu catálogo

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

Esa es toda la exportación. El endpoint transmite todas las entidades que Backstage conoce: Systems, Components, Resources, APIs, Groups, Users — todo. Para la mayoría de las organizaciones, obtienes un array JSON de 5 a 30 MB con miles de entradas.

Si estás probando sin auth (algunas instancias de Backstage permiten lecturas públicas del catálogo en la red interna), puedes omitir el header Authorization. Si necesitas filtrar por kind para mantener el archivo más pequeño, Backstage soporta query params: ?filter=kind=component,kind=system,kind=api,kind=resource reducirá la respuesta solo a lo que Archyl realmente mapea.

Paso 2 — Abre el diálogo de importación

En Archyl, haz clic en Importar Proyecto (o Importar dentro de un proyecto existente), selecciona la pestaña Backstage y sube entities.json o pégalo directamente.

Archyl valida el archivo y luego te muestra exactamente qué se creará — número de sistemas, contenedores, contratos de API, relaciones — antes de que se escriba nada.

Paso 3 — Haz clic en importar

Tu proyecto se llena. Un catálogo de 9 MB con ~3.000 entidades se importa en segundos. Ahora puedes hacer clic en cualquier sistema, ver sus contenedores dispuestos en C4 Level 2, profundizar en las APIs y seguir las aristas dependsOn a través de tu stack.

Qué se mapea realmente

La parte difícil de importar desde Backstage no es leer el JSON — es traducir entre dos modelos mentales diferentes. Backstage piensa en entidades planas conectadas por relaciones tipadas. C4 piensa en niveles anidados. Así es como Archyl tiende el puente:

Backstage Archyl Notas
System C4 System (Nivel 1) Los sistemas con el mismo nombre en namespaces distintos se desambiguan automáticamente
Component Container bajo su System propietario service → service, cronworkflow → worker, website → web_app
Resource Container bajo su System propietario Consciente del tipo: 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) Contrato de API Las specs OpenAPI 3, gRPC, GraphQL, AsyncAPI se preservan inline y se enlazan con los componentes proveedores/consumidores
dependsOn, dependencyOf Relación depends_on Los pares bidireccionales se deduplican automáticamente
consumesApi Relación uses Resuelta a través de la API hasta su componente proveedor real
producesTo, producedBy Relación publishes_to
consumesFrom, consumedBy Relación consumes_from
versionedIn, versions Relación depends_on Etiquetada como "source code"
metadata.namespace, spec.lifecycle, spec.type, metadata.tags Tags Todos transferidos para filtrado y overlays
User, Group Omitidos El grafo de personas no es un concepto C4

Los Components y Resources sin spec.system van a un sistema sintético llamado Uncategorized para que nada se descarte silenciosamente.

Los dos detalles que más importan en la práctica:

  • Los contratos de API vienen con su contenido. Cada entidad API de Backstage que incluye una spec.definition (tu YAML OpenAPI inline, tu .proto gRPC) se importa como un Contrato de API de Archyl con la spec completa adjunta y vinculada al componente proveedor. No hay que volver a subir specs a mano.
  • Los tipos de Resource se preservan. Un topic de Kafka no se convierte en un "service" genérico — es un container message_queue. Una instancia de RDS es una database. Un bucket S3 es file_storage. Tu modelo visual refleja la naturaleza real de cada pieza de infraestructura.

Una palabra sobre la proliferación de recursos

Si tu organización corre fuertemente sobre Kubernetes, tu catálogo de Backstage probablemente tenga cientos — quizás miles — de recursos external-secret, repository, datadog-service y load-balancer auto-descubiertos desde clusters. Los importamos todos.

Eso podría parecer mucho a primera vista. Lo es.

Pero tienes varias opciones:

  • Mantenerlos y filtrar. Cada container importado lleva un tag type:external-secret (o lo que corresponda). Los overlays y filtros de tags de Archyl te permiten ocultarlos en el diagrama mientras siguen siendo consultables.
  • Eliminar en masa lo que es ruido. Dos clics por tipo para eliminar una categoría completa si no la quieres en tu modelo.
  • Re-exportar con un filtro. Usa los query params ?filter= de Backstage para excluir tipos de recursos que no te interesan antes de importar.

Elegimos importar todo porque la alternativa — descartar silenciosamente datos que pensamos que no necesitabas — es peor. Tú curaste tu catálogo. Tú decides qué se queda.

Lo que realmente ganas

Un catálogo de Backstage te dice qué existe. Una arquitectura Archyl te dice qué está pasando.

Una vez que tu catálogo vive en Archyl, desbloqueas cosas que Backstage simplemente no hace:

Un diagrama C4 real. Interactivo, con zoom, navegable a través de los cuatro niveles — Contexto del Sistema, Container, Component y Code. Haz clic en cualquier servicio para profundizar en sus internals. Sigue una relación a través del stack.

Detección de drift. Archyl compara continuamente tu arquitectura documentada con el código real en tus repositorios. Cuando tu catálogo dice "el Servicio A llama al Servicio B" pero el código dejó de hacerlo hace seis meses, lo descubres — en lugar de descubrirlo durante un incidente.

Reglas de conformidad de arquitectura. Codifica "ningún servicio fuera del dominio de pagos puede llamar a legacy-auth-api", o "todas las llamadas externas deben pasar por el API gateway". Archyl las aplica automáticamente y muestra las violaciones en cada PR.

Inteligencia de contratos de API. Las specs OpenAPI que has alimentado a Backstage ahora viven dentro de la arquitectura, vinculadas a productores y consumidores. ¿Cambio que rompe en news-api? Mira exactamente qué servicios downstream dependen de ella.

Métricas DORA ligadas a la arquitectura. Conecta la frecuencia de despliegue, lead time, tasa de fallos en cambios y MTTR a sistemas, containers y equipos específicos. Mira qué partes de tu arquitectura están sanas y cuáles están en problemas.

Architecture Decision Records. Por fin tendrás un lugar donde escribir el por qué junto al qué, vinculado directamente a los sistemas y componentes afectados.

Integración MCP. Cada agente de codificación de IA en tu equipo — Claude Code, Cursor, Windsurf — comparte el mismo contexto de arquitectura. Deja de re-explicar a tu LLM cómo encajan tus servicios.

El catálogo de Backstage responde "¿qué servicios tenemos?". Archyl responde "¿cómo están conectados, qué está derivando, qué está en riesgo y dónde deberíamos invertir?". Importar tu catálogo significa que no tienes que elegir entre los dos.

Para flujos de trabajo de agentes IA

La misma importación está expuesta a través del servidor MCP de Archyl. Apunta Claude Code, Cursor o cualquier agente de codificación IA a la herramienta import_dsl con format: "backstage" y el contenido de tu entities.json — y tu arquitectura aterriza sin que nadie toque un navegador.

Usa la herramienta import_dsl con:
- projectId: <UUID de tu proyecto>
- content: <contenido de entities.json>
- format: "backstage"

Útil cuando estás scripteando syncs de catálogo desde CI, o cuando quieres que tu asistente IA refresque el modelo después de una actualización mayor de Backstage.

Pruébalo ahora

Si tu equipo usa Backstage hoy, estás literalmente a un curl de una arquitectura C4 completa.

  1. Ejecuta el curl de arriba.
  2. Abre Archyl, haz clic en Importar Proyecto, elige Backstage.
  3. Mira cómo tus servicios, APIs, queues y bases de datos encajan en una arquitectura navegable.

La importación funciona en cada plan, incluyendo el tier gratuito. No creemos que tu decisión deba depender de si tu catálogo es portable — debería depender de qué quieres hacer con él a continuación.

Tu catálogo de Backstage ha estado esperando para convertirse en una arquitectura. Ve a hacerla realidad.