Importar un catalogo de Backstage en Archyl: Backstage a C4

Convierte tu Software Catalog de Backstage en un modelo C4 navegable. System, Component, Resource y specs de API inline se importan desde entities.json.

Importación de Backstage

Importa tu catálogo de Backstage en Archyl

Backstage lista lo que ejecutas. Archyl convierte ese mismo catálogo en un modelo C4 navegable: los System se convierten en sistemas, los Component y los Resource se convierten en contenedores, y cada entidad API se convierte en un contrato con su spec preservada tal cual y vinculada a los servicios que la proveen y la consumen. Conservas Backstage. La propiedad no se transfiere, y obtienes dos niveles C4 sobre los que construir.

Importar un catálogo de Backstage en Archyl | Backstage a C4

Convierte tu Software Catalog de Backstage en un modelo de arquitectura C4 navegable. System, Component, Resource y specs de API inline se importan desde entities.json. La propiedad se queda en Backstage.

Backstage a C4, importar catálogo Backstage, exportar catálogo Backstage, diagrama de arquitectura Backstage, modelo C4 Backstage software catalog, documentación de arquitectura Backstage

Cada entidad System se convierte en un sistema de software C4 con su descripción y sus tags. Dos System que comparten nombre en distintos namespaces se renombran en lugar de fusionarse, y la importación te dice cuáles.

Los Component se convierten en contenedores bajo el System que los posee, resuelto desde spec.system o una relación partOf. Su spec.type se mapea: service a servicio, website a aplicación web, cronworkflow a worker, library a librería.

Los Resource también se convierten en contenedores, tipados desde spec.type. Las instancias RDS y los clústeres Valkey se convierten en bases de datos, los topics de Kafka y las colas SQS en colas de mensajes, los buckets S3 en almacenamiento de archivos.

Las entidades API se convierten en contratos de API de Archyl. El spec.definition inline se conserva literalmente, tipado como HTTP, gRPC, GraphQL o async, y vinculado a los contenedores que lo proveen y lo consumen.

dependsOn, consumesApi, producesTo, consumesFrom y versionedIn se convierten en relaciones tipadas. Backstage emite la mayoría de las relations en ambos sentidos y la importación conserva una. Una arista consumesApi se resuelve a través de la API hasta el contenedor que realmente la provee.

Namespaces y lifecycle

Tus metadata.tags llegan sin cambios, junto a namespace, lifecycle y type como tags con prefijo, para que la agrupación que curaste en Backstage sobreviva en el modelo de arquitectura.

Llama a la API catalog de tu Backstage y guarda la respuesta. El endpoint entities devuelve cada System, Component, Resource y API que conoce como un único array JSON.

Elige el formato Backstage

En el diálogo de importación de Archyl, elige la pestaña "Backstage". Acepta el array entities exactamente como lo exporta Backstage, sin reformatear nada.

Sube o pega entities.json

Sube el archivo o pégalo, y luego valida. Archyl informa de cualquier error del JSON antes de que confirmes la importación.

Importa y lee los avisos

Archyl construye el modelo e informa de cuántos sistemas, contenedores, contratos de API y relaciones ha creado, además de cada entidad que ha tenido que renombrar. Asigna los propietarios después: los Group y User de Backstage no se importan.

Obtén una puntuación de salud 0-100% que muestra la fidelidad de tu documentación respecto a tu código fuente. Detecta la deriva antes de que se acumule.

Reglas de conformidad

Define reglas de arquitectura y ejecuta verificaciones automatizadas para garantizar que tu sistema se mantiene dentro de los límites definidos.

Rastrea la frecuencia de despliegue, el tiempo de entrega, la tasa de fallos y el tiempo de recuperación junto con la salud de tu arquitectura.

Servidor MCP (181 herramientas)

Consulta datos de arquitectura desde Claude, Cursor o Windsurf a través de 181 herramientas MCP especializadas.

Architecture Decision Records

Vincula los ADR directamente a los elementos C4 para que cada decisión de diseño tenga un contexto trazable.

Adjunta esquemas OpenAPI, AsyncAPI o GraphQL a contenedores y componentes. Mantén los contratos versionados con tu arquitectura.

¿Tenemos que dejar Backstage?

No, y la mayoría de los equipos no deberían. Backstage es un portal para desarrolladores; Archyl es un modelo de arquitectura. La importación lee un export del catálogo y nunca toca tu instancia de Backstage, así que ambos siguen funcionando. Archyl responde a las preguntas que un catálogo plano no puede: cómo encajan estos servicios entre sí, qué se ha desviado del código y qué contratos se rompen si uno de ellos cambia.

¿Cuántos niveles C4 me da la importación?

Dos. Los System aterrizan en el nivel 1 de C4, y tanto los Component como los Resource aterrizan en el nivel 2 como contenedores. Backstage no tiene ningún kind de entidad por debajo de Component, así que no hay nada con lo que rellenar el nivel 3. Los componentes y los elementos de código los añades después a mano, o apuntas el descubrimiento IA de Archyl al repositorio y apruebas lo que propone.

¿Se transfiere la propiedad?

No. Las entidades User y Group se omiten y las relaciones ownedBy no se mapean, por lo que spec.owner no se convierte en un propietario en Archyl. Esto es lo único que conviene planificar: si usas el mapa de propiedad de Archyl, asignas los propietarios después de la importación.

¿Qué pasa con nuestras specs de OpenAPI y gRPC?

Una entidad API que lleve un spec.definition inline conserva esa spec literalmente como contrato de API de Archyl, tipada desde spec.type como HTTP, gRPC, GraphQL o async, y vinculada a los contenedores que la proveen y la consumen. Una entidad API sin definición inline también llega con su nombre, descripción y tipo, pero sin cuerpo.

¿Qué omite la importación?

Las entidades User y Group, junto con las relaciones ownedBy que apuntan a ellas. Las entidades Location y Template. Los bloques metadata.annotations y metadata.links, lo que significa que el puntero a TechDocs no llega. Las relations fuera del conjunto mapeado se ignoran. La importación te avisa de las entidades duplicadas y renombradas. Los kinds anteriores se descartan sin aviso, y por eso esta página los nombra.

Nuestro catálogo tiene miles de Resource descubiertos automáticamente. ¿Entran todos?