Backstage vs Archyl: Dos enfoques para la documentación de arquitectura
Si estás evaluando herramientas para documentación de arquitectura, probablemente hayas mirado Backstage. Es open-source, está respaldado por Spotify, y tiene un ecosistema de plugins que cubre todo, desde CI/CD hasta gestión de costos. Uno de esos plugins maneja diagramas C4.
Archyl toma el enfoque opuesto. No es un portal de desarrollador. No gestiona pipelines de CI ni catálogos de servicios. Hace una sola cosa: documentación de arquitectura con el modelo C4 — y profundiza en ello.
Este artículo no es un "qué herramienta es mejor". Sirven propósitos diferentes. Pero si lo que realmente necesitas es documentación de arquitectura, las diferencias importan. Permíteme detallarlas.
La filosofía central
Backstage es un framework de portal de desarrollador. Su trabajo es unificar todas las herramientas, servicios y documentación que un equipo de desarrollo utiliza en una única plataforma interna. La documentación de arquitectura es uno de los muchos plugins disponibles — es una funcionalidad dentro de un ecosistema más amplio.
Archyl es una plataforma de documentación de arquitectura construida con propósito específico. Todo el producto existe para modelar, visualizar, analizar y evolucionar la arquitectura de software usando el modelo C4. Cada funcionalidad alimenta ese único propósito.
Esta diferencia de alcance moldea todo lo demás.
Soporte del modelo C4
Backstage
El modelo de entidades de Backstage incluye Components, APIs, Resources, Systems, Domains, Groups y Users. Esto se mapea aproximadamente a los niveles C4 1 y 2 — sistemas y contenedores. Pero el mapeo es aproximado, no preciso.
El plugin C4 para Backstage (backstage-plugin-c4-model) renderiza diagramas a partir de las entidades existentes del catálogo. Soporta vistas de Contexto de Sistema y Contenedor. No hay soporte nativo para el C4 Nivel 3 (Componentes) ni Nivel 4 (Código). Si tu modelado arquitectónico necesita ir por debajo del nivel de contenedor, te encuentras con un muro.
El catálogo en sí está dirigido por YAML. Cada entidad se define en archivos catalog-info.yaml, típicamente commiteados junto al código. Esto significa que la arquitectura se define en archivos de configuración, no en una herramienta visual.
Archyl
Archyl implementa nativamente los cuatro niveles C4:
- Nivel 1 — Contexto de Sistema: Sistemas, sistemas externos y personas
- Nivel 2 — Contenedor: Aplicaciones, servicios, bases de datos, colas de mensajes, cachés y más
- Nivel 3 — Componente: Controladores, servicios, repositorios, handlers, middleware, modelos
- Nivel 4 — Código: Clases, interfaces, funciones, métodos, enums, constantes
Cada nivel tiene sus propios tipos de nodos, estilos visuales y metadatos. Puedes descender desde un sistema a sus contenedores, desde un contenedor a sus componentes, desde un componente a sus elementos de código — todo dentro del mismo diagrama interactivo. Las relaciones entre elementos en cualquier nivel son ciudadanos de primera clase con conexiones tipadas (uses, depends_on, calls, reads_from, writes_to, etc.).
La diferencia: Backstage te da un catálogo con vistas C4 añadidas encima. Archyl te da un entorno completo de modelado C4 donde puedes representar toda tu arquitectura a cualquier nivel de detalle.
Visualización
Backstage
El plugin C4 genera diagramas estáticos o semi-interactivos a partir de los datos del catálogo. La visualización depende de la implementación específica del plugin — algunos usan PlantUML, otros Structurizr, otros renderizan en el navegador. Pero la experiencia es fundamentalmente de solo lectura. Visualizas diagramas generados desde definiciones YAML. No interactúas con ellos.
No hay manipulación de canvas, ni posicionamiento de arrastrar y soltar, ni colaboración en tiempo real en los diagramas. Para cambiar la representación de la arquitectura, editas archivos YAML y esperas a que el catálogo se actualice.
Archyl
Archyl proporciona un canvas completamente interactivo construido sobre React Flow. Puedes:
- Arrastrar y posicionar cualquier elemento en el diagrama
- Dibujar relaciones entre elementos directamente en el canvas
- Navegar entre niveles C4 entrando en sistemas, contenedores y componentes
- Ver cursores en tiempo real de compañeros trabajando en el mismo diagrama
- Usar auto-layout para organizar elementos automáticamente, o posicionarlos manualmente
- Aplicar overlays para agrupar visualmente elementos relacionados
- Cambiar entre temas claro y oscuro en el diagrama
El canvas es el espacio de trabajo principal, no un artefacto generado. Cada cambio que haces en el diagrama se refleja instantáneamente.
Descubrimiento con IA
Backstage
Backstage no tiene descubrimiento de arquitectura con IA integrado. Para poblar el catálogo, creas manualmente archivos catalog-info.yaml para cada servicio, o usas proveedores de entidades que importan desde fuentes externas (Kubernetes, GitHub, etc.). Algunos plugins comunitarios añaden capacidades de IA, pero no hay análisis nativo de arquitectura desde el código.
Si tienes 200 servicios y ninguno tiene archivos catalog-info.yaml, estás escribiendo 200 archivos YAML a mano — o construyendo herramientas personalizadas para generarlos.
Archyl
Archyl incluye descubrimiento con IA integrado que se conecta a tu repositorio Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, o repositorios locales), lee tu código fuente, y genera automáticamente un modelo C4 completo.
El pipeline de descubrimiento:
- Se conecta a tu repositorio
- Analiza archivos fuente, código de infraestructura y configuración
- Identifica sistemas, contenedores, componentes y sus relaciones
- Detecta dependencias desde manifiestos de paquetes
- Genera un modelo C4 propuesto con auto-layout
- Presenta el resultado para tu revisión y aprobación
Puedes aprobar, modificar o rechazar cualquier parte del modelo generado. La IA se encarga del trabajo pesado de mapeo inicial de arquitectura; tú aportas el criterio.
El sistema entiende Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, Kubernetes YAML, charts Helm, y más.
Architecture Decision Records
Backstage
Los ADRs en Backstage se manejan típicamente a través del plugin ADR, que lee archivos markdown ADR desde un repositorio. Los muestra en la interfaz de Backstage, generalmente siguiendo el formato MADR (Markdown Architectural Decision Records). Los ADRs viven en Git como archivos markdown.
No hay vinculación entre ADRs y entidades del catálogo. Un ADR sobre elegir PostgreSQL en vez de MongoDB está en una carpeta /docs/adr/ — no hay conexión directa con el contenedor de base de datos que referencia.
Archyl
Los ADRs en Archyl son objetos de primera clase vinculados directamente a elementos C4. Cuando creas un ADR, puedes adjuntarlo a sistemas, contenedores, componentes o elementos de código específicos. Esto significa:
- Abre un contenedor en el diagrama y ves sus ADRs relacionados
- Navega por los ADRs y ve exactamente qué elementos de arquitectura afectan
- Comprende el razonamiento detrás de las decisiones arquitectónicas en contexto
Los ADRs soportan estados (propuesto, aceptado, deprecado, reemplazado) y contenido markdown enriquecido con secciones estructuradas para contexto, decisión y consecuencias.
Documentación
Backstage
El sistema TechDocs de Backstage convierte archivos markdown (típicamente usando MkDocs) en documentación navegable dentro del portal. Es basado en markdown y respaldado por Git. La documentación se renderiza bien y soporta búsqueda.
Sin embargo, TechDocs es documentación de propósito general, no documentación de arquitectura. No hay conexión estructural entre los docs y el modelo de arquitectura. Una página sobre "Arquitectura de Autenticación" no enlaza con el sistema de autenticación en el diagrama.
Archyl
El sistema de documentación de Archyl está integrado con el modelo de arquitectura. Los elementos de documentación pueden vincularse a elementos C4, organizarse en carpetas y accederse en contexto junto a los diagramas. Cuando visualizas un sistema o contenedor, su documentación relacionada es visible en el panel lateral.
No se trata de reemplazar herramientas de documentación general. Se trata de asegurar que la documentación de arquitectura vive junto a la arquitectura que describe.
Análisis de impacto
Backstage
Backstage no tiene capacidad de análisis de impacto. Si quieres entender qué se rompe cuando deprecas un servicio, trazas dependencias manualmente a través del catálogo. No hay análisis automatizado upstream/downstream, ni puntuación de riesgo, ni simulación de escenarios.
Algunas organizaciones construyen scripts o plugins personalizados para analizar las relaciones del catálogo, pero no hay nada integrado.
Archyl
El Impact Radar de Archyl proporciona análisis de impacto completo directamente en el diagrama. Haz clic derecho en cualquier elemento y ve instantáneamente:
- Dependientes upstream y dependencias downstream organizados por grado (1, 2, 3 saltos)
- Puntuación de riesgo calculada desde dependientes upstream, alcance downstream, hijos estructurales y ratio de acoplamiento
- Camino crítico resaltando la cadena de dependencias más larga
- Dependencias entre proyectos al usar Arquitectura Global
- Flujos afectados cruzados con los recorridos de usuario documentados
- Simulación de escenarios mostrando exactamente qué se rompe si un elemento es eliminado
El análisis se ejecuta de forma determinista sobre el grafo de relaciones. Sin suposiciones, sin reuniones para averiguar quién está afectado.
Gestión del cambio
Backstage
Los cambios al catálogo de Backstage pasan por Git. Creas un PR que modifica catalog-info.yaml, lo revisas y lo mergeas. Es el workflow Git estándar — no hay gestión de cambio específica para la arquitectura.
La revisión ocurre en GitHub/GitLab, no en el contexto de la arquitectura. Los revisores ven diffs de YAML, no diffs visuales de cómo cambia la arquitectura.
Archyl
Archyl tiene Solicitudes de Cambio de Arquitectura dedicadas — un workflow tipo pull-request específicamente para cambios de arquitectura. Propones modificaciones al modelo C4, los revisores ven exactamente qué se agrega, modifica o elimina, y el cambio pasa por un proceso de aprobación antes de aplicarse.
Esto aporta gobernanza a la evolución de la arquitectura sin forzar todo a pasar por archivos YAML y diffs de Git.
Colaboración
Backstage
Backstage es un portal web. Múltiples personas pueden acceder simultáneamente, pero no hay colaboración en tiempo real en la arquitectura misma. Consultas el catálogo de manera independiente. No hay cursores en vivo, ni indicadores de presencia, ni edición concurrente.
Archyl
Archyl proporciona colaboración en tiempo real en diagramas C4:
- Cursores en vivo mostrando dónde están tus compañeros en el canvas
- Indicadores de presencia mostrando quién está viendo el diagrama
- Seguimiento de foco para ver qué elementos están trabajando tus compañeros
- Edición concurrente con resolución de conflictos
Esto se extiende tanto a los diagramas C4 a nivel de proyecto como a la vista de Arquitectura Global.
Datos operacionales en tiempo real
Una de las mayores sorpresas al descubrir Archyl es el Marketplace. La documentación de arquitectura no es solo diagramas estáticos — Archyl se conecta a las herramientas que tus equipos ya usan y muestra datos en vivo directamente sobre tu arquitectura.
Backstage
El ecosistema de plugins de Backstage es su fortaleza principal aquí. Hay plugins para casi todo — estado de CI/CD, dashboards de monitoreo, seguimiento de costos, estado de Kubernetes, y más. Pero estos plugins viven en sus propias páginas dentro del portal. No están conectados a la vista de arquitectura. Ves el estado de CI/CD de un servicio en su página de catálogo, pero no en el diagrama C4 donde ese servicio vive en contexto con todo lo que depende de él.
Archyl
El Marketplace de Archyl proporciona integraciones que muestran datos en vivo como widgets directamente en tus dashboards de arquitectura:
- CI/CD: Estado de workflows de GitHub Actions, PRs abiertas, alertas de Dependabot, escaneo de seguridad. Estado de pipelines de GitLab, merge requests, reportes de vulnerabilidades, alertas SAST/DAST. Estado de aplicaciones Argo CD y seguimiento de despliegues.
- Observabilidad: Dashboards embebidos de Datadog, consultas de métricas, estado de monitores. Consultas instantáneas y de rango de Prometheus, salud de targets. Seguimiento de errores de Sentry.
- Calidad de código: Estado del quality gate de SonarQube, medidas de código, issues, hotspots de seguridad y calificaciones.
- Gestión de incidentes: Estado de incidentes de PagerDuty, incidentes activos, guardias on-call, salud de servicios.
Los widgets se actualizan automáticamente y pueden acotarse a tres niveles — organización, por proyecto, o adjuntos a un elemento C4 específico. Un contenedor que representa tu servicio de pagos puede mostrar su estado de build de GitHub Actions, su quality gate de SonarQube, sus métricas de salud de Datadog y su guardia on-call de PagerDuty, todo en un solo lugar.
Esto transforma la documentación de arquitectura de una referencia estática en una vista operacional viva. El diagrama no solo muestra cómo se ve tu sistema — muestra cómo está funcionando ahora mismo.
Más allá de lo básico
Algunas áreas adicionales donde los enfoques divergen:
| Capacidad | Backstage | Archyl |
|---|---|---|
| Contratos de API | Entidades API en catálogo, algo de renderizado OpenAPI | Contratos OpenAPI/gRPC/GraphQL completos vinculados a elementos C4 |
| Canales de eventos | Sin soporte nativo | Canales Kafka, NATS, SQS, RabbitMQ, Redis, Pulsar vinculados a elementos |
| Flujos de usuario | Sin soporte nativo | Diagramas de flujo paso a paso vinculados a elementos de arquitectura |
| Insights de arquitectura | Sin soporte nativo | Recomendaciones generadas por IA con puntuación de severidad |
| Gestión de releases | Sin soporte nativo | Seguimiento de despliegues a través de entornos y sistemas |
| Arquitectura Global | Sin vista entre proyectos | Vista global conectando sistemas a través de múltiples proyectos |
| Servidor MCP | Sin soporte nativo | Claude, Cursor y otras herramientas IA pueden leer/escribir tu modelo |
| Export/Import | Catálogo basado en YAML | Export/import JSON para portabilidad completa del proyecto |
| On-Premise | Auto-hospedado (obligatorio) | Cloud o auto-hospedado (Docker, Kubernetes, Helm) |
Cuándo elegir qué
Elige Backstage si necesitas un portal de desarrollador unificado que agregue documentación, CI/CD, catálogo de servicios, gestión de costos y docenas de otras preocupaciones en una única plataforma interna. La documentación de arquitectura es una pieza de ese puzzle, y una vista C4 de alto nivel es suficiente para tus necesidades.
Elige Archyl si la documentación de arquitectura es una preocupación primaria — pero sin sacrificar la visibilidad operacional para conseguirlo. Archyl profundiza en el modelo C4 (los 4 niveles), diagramas interactivos, descubrimiento con IA, análisis de impacto y gobernanza del cambio, mientras que sus integraciones del Marketplace traen el estado de CI/CD, monitoreo, calidad de código y datos de incidentes directamente a tu arquitectura. Obtienes herramientas de arquitectura enfocadas sin perder el contexto operacional que Backstage proporciona a través de su ecosistema de plugins.
También pueden coexistir. Archyl maneja el modelado arquitectónico detallado, el análisis y la visibilidad operacional acotada a tu arquitectura. Backstage maneja la experiencia de desarrollador más amplia — onboarding, búsqueda en catálogo, dashboards de costos y documentación general. El modelo de arquitectura en Archyl puede informar lo que documentes en el catálogo de servicios de Backstage, sin que una herramienta reemplace a la otra.
En resumen
Backstage es un framework de plataforma que ensamblas a partir de plugins. Es potente, flexible, y resuelve el problema de la fragmentación de la experiencia de desarrollador. Pero sus capacidades de documentación de arquitectura se limitan a lo que los plugins C4 dirigidos por catálogo pueden ofrecer — típicamente niveles 1 y 2, vistas estáticas, sin IA, sin análisis de impacto, sin colaboración en tiempo real en diagramas.
Archyl es una herramienta enfocada que profundiza en la arquitectura. Cubre el modelo C4 completo, descubrimiento con IA, análisis de impacto, gobernanza del cambio, colaboración en tiempo real — y se conecta a tus herramientas de CI/CD, observabilidad, calidad de código y gestión de incidentes para que tu arquitectura se mantenga anclada en la realidad operacional. No es un portal de desarrollador, pero es mucho más que documentación estática.
Tu arquitectura merece más que una entrada de catálogo.
¿Nuevo en el modelo C4? Empieza con nuestra Introducción al Modelo C4. ¿Ya estás modelando? Prueba el Descubrimiento de Arquitectura con IA para arrancar tu primer proyecto desde el código, o explora Impact Radar para entender el cambio antes de hacerlo.