Backstage vs Archyl: duas abordagens para documentação de arquitetura

Se você está avaliando ferramentas de documentação de arquitetura, provavelmente já olhou o Backstage. Ele é open source, tem o apoio do Spotify e um ecossistema de plugins que cobre de tudo, de CI/CD a gestão de custos. Um desses plugins cuida de diagramas C4.

O Archyl segue a abordagem oposta. Ele não é um developer portal. Não gerencia pipelines de CI nem catálogos de serviços. Faz uma coisa só: documentação de arquitetura com o modelo C4, e vai fundo nisso.

Este não é um artigo sobre "qual ferramenta é melhor". Elas servem a propósitos diferentes. Mas, se o que você precisa de verdade é documentação de arquitetura, as diferenças importam. Vamos passar por elas.

A filosofia central

O Backstage é um framework de developer portal. O trabalho dele é unificar em uma única plataforma interna todas as ferramentas, serviços e documentação que uma equipe de desenvolvimento usa. A documentação de arquitetura é um entre muitos plugins disponíveis: um recurso dentro de um ecossistema maior.

O Archyl é uma plataforma feita especificamente para documentação de arquitetura. O produto inteiro existe para modelar, visualizar, analisar e evoluir a arquitetura de software com o modelo C4. Cada recurso volta para esse único propósito.

Essa diferença de escopo molda todo o resto.

Suporte ao modelo C4

Backstage

O modelo de entidades do Backstage inclui Components, APIs, Resources, Systems, Domains, Groups e Users. Isso corresponde, de forma aproximada, aos níveis 1 e 2 do C4, ou seja, sistemas e containers. Mas a correspondência é aproximada, não precisa.

O plugin C4 para o Backstage (backstage-plugin-c4-model) renderiza diagramas a partir das entidades já existentes no catálogo. Ele suporta as visões System Context e Container. Não há suporte nativo ao nível 3 do C4 (Component) nem ao nível 4 (Code). Se a sua modelagem precisa ir abaixo do nível de container, você bate em uma parede.

O catálogo em si é orientado a YAML. Cada entidade é definida em arquivos catalog-info.yaml, normalmente commitados junto com o código. Isso significa que a arquitetura é definida em arquivos de configuração, não em uma ferramenta visual, e ela é importada para um modelo C4 com um único upload.

Archyl

O Archyl implementa os quatro níveis do C4 de forma nativa:

• Nível 1 — System Context: sistemas, sistemas externos e pessoas
• Nível 2 — Container: aplicações, serviços, bancos de dados, filas de mensagens, caches e mais
• Nível 3 — Component: controllers, serviços, repositórios, handlers, middleware, modelos
• Nível 4 — Code: classes, interfaces, funções, métodos, enums, constantes

Cada nível tem seus próprios tipos de nó, estilos visuais e metadados. Você pode descer de um sistema para seus containers, de um container para seus componentes, de um componente para seus elementos de código, tudo no mesmo diagrama interativo. Os relacionamentos entre elementos de qualquer nível são cidadãos de primeira classe, com conexões tipadas (uses, depends_on, calls, reads_from, writes_to etc.).

A diferença: o Backstage dá a você um catálogo com visões C4 acopladas. O Archyl dá a você um ambiente completo de modelagem C4, em que você representa toda a sua arquitetura em qualquer nível de detalhe.

Visualização

Backstage

O plugin C4 gera diagramas estáticos ou semi-interativos a partir dos dados do catálogo. A visualização depende da implementação específica do plugin: alguns usam PlantUML, outros Structurizr, outros renderizam no navegador. Mas a experiência é, no fundo, somente leitura. Você vê diagramas gerados a partir de definições YAML. Você não interage com eles.

Não há manipulação de canvas, nem posicionamento com drag-and-drop, nem colaboração em tempo real nos diagramas. Para mudar a representação da arquitetura, você edita arquivos YAML e espera o catálogo atualizar.

Archyl

O Archyl oferece um canvas totalmente interativo construído com React Flow. Você pode:

• Arrastar e posicionar qualquer elemento do diagrama
• Desenhar relacionamentos entre elementos direto no canvas
• Navegar entre os níveis C4 entrando em sistemas, containers e componentes
• Ver em tempo real os cursores dos colegas que trabalham no mesmo diagrama
• Usar o auto-layout para organizar os elementos automaticamente, ou posicioná-los à mão
• Aplicar overlays para agrupar visualmente elementos relacionados
• Alternar entre os temas claro e escuro no diagrama

O canvas é o espaço de trabalho principal, não um artefato gerado. Cada mudança feita no diagrama aparece na hora.

Descoberta com IA

Backstage

O Backstage não tem descoberta de arquitetura com IA integrada. Para preencher o catálogo, você cria à mão arquivos catalog-info.yaml para cada serviço, ou usa entity providers que importam de fontes externas (Kubernetes, GitHub etc.). Alguns plugins da comunidade acrescentam recursos de IA, mas não há análise nativa da arquitetura a partir do código.

Se você tem 200 serviços e nenhum tem um arquivo catalog-info.yaml, você vai escrever 200 arquivos YAML à mão, ou construir ferramentas próprias para gerá-los.

Archyl

O Archyl inclui descoberta com IA integrada que se conecta ao seu repositório Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea ou repositórios locais), lê o seu código e gera automaticamente um modelo C4 completo.

O pipeline de descoberta:

1. Conecta-se ao seu repositório
2. Analisa arquivos-fonte, código de infraestrutura e configuração
3. Identifica sistemas, containers, componentes e seus relacionamentos
4. Detecta dependências a partir dos manifestos de pacotes
5. Gera uma proposta de modelo C4 com auto-layout
6. Apresenta o resultado para sua revisão e aprovação

Você pode aprovar, modificar ou rejeitar qualquer parte do modelo gerado. A IA faz o trabalho pesado do mapeamento inicial da arquitetura; você entra com o julgamento.

O sistema entende Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, YAML de Kubernetes, charts Helm e mais.

Architecture Decision Records

Backstage

No Backstage, os ADRs costumam ser tratados pelo plugin de ADR, que lê os arquivos markdown dos ADRs de um repositório. Ele os exibe na interface do Backstage, muitas vezes no formato MADR (Markdown Architectural Decision Records). Os ADRs vivem no Git como arquivos markdown.

Não existe vínculo entre ADRs e entidades do catálogo. Um ADR sobre a escolha de PostgreSQL em vez de MongoDB fica em uma pasta /docs/adr/, sem nenhuma conexão direta com o container do banco de dados ao qual ele se refere.

Archyl

No Archyl, os ADRs são objetos de primeira classe vinculados diretamente aos elementos C4. Quando você cria um ADR, pode associá-lo a sistemas, containers, componentes ou elementos de código específicos. Isso significa:

• Abrir um container no diagrama e ver os ADRs relacionados a ele
• Navegar pelos ADRs e ver exatamente quais elementos da arquitetura eles afetam
• Entender o raciocínio por trás das escolhas de arquitetura no contexto

Os ADRs suportam status (proposed, accepted, deprecated, superseded) e conteúdo markdown rico, com seções estruturadas para contexto, decisão e consequências.

Documentação

Backstage

O sistema TechDocs do Backstage converte arquivos markdown (normalmente com MkDocs) em documentação navegável dentro do portal. Ele é baseado em markdown e versionado no Git. A documentação é bem renderizada e tem busca.

Porém, o TechDocs é documentação de propósito geral, não documentação de arquitetura. Não há conexão estrutural entre os documentos e o modelo de arquitetura. Uma página sobre "Arquitetura de autenticação" não se liga ao sistema de autenticação no diagrama.

Archyl

O sistema de documentação do Archyl é integrado ao modelo de arquitetura. Os itens de documentação podem ser vinculados a elementos C4, organizados em pastas e acessados no contexto, ao lado dos diagramas. Quando você vê um sistema ou container, a documentação relacionada aparece no painel lateral.

Não se trata de substituir ferramentas de documentação geral. Trata-se de garantir que a documentação de arquitetura viva ao lado da arquitetura que ela descreve.

Análise de impacto

Backstage

O Backstage não tem nenhum recurso de análise de impacto. Se você quer entender o que quebra ao descontinuar um serviço, rastreia as dependências manualmente pelo catálogo. Não há análise automática upstream/downstream, nem pontuação de risco, nem simulação what-if.

Algumas organizações criam scripts ou plugins próprios para analisar os relacionamentos do catálogo, mas não há nada integrado.

Archyl

O Impact Radar do Archyl oferece uma análise de impacto completa direto no diagrama. Clique com o botão direito em qualquer elemento e veja na hora:

• Dependentes upstream e dependências downstream, organizados por grau (1, 2, 3 saltos)
• Pontuação de risco calculada a partir dos dependentes upstream, do alcance downstream, dos filhos estruturais e da taxa de acoplamento
• Caminho crítico, destacando a cadeia de dependências mais longa
• Dependências entre projetos quando você usa a Arquitetura Global
• Fluxos afetados, cruzados com as jornadas de usuário documentadas
• Simulação what-if mostrando exatamente o que quebra se um elemento for removido

A análise roda de forma determinística sobre o grafo de relacionamentos. Sem palpites, sem reuniões para descobrir quem é afetado.

Gestão de mudanças

Backstage

As mudanças no catálogo do Backstage passam pelo Git. Você cria um PR que altera o catalog-info.yaml, pede revisão e faz o merge. É o fluxo padrão do Git: não há gestão de mudanças específica para arquitetura.

A revisão acontece no GitHub/GitLab, não no contexto da arquitetura. Quem revisa vê diffs de YAML, não diffs visuais de como a arquitetura muda.

Archyl

O Archyl tem Architecture Change Requests dedicadas: um fluxo parecido com pull request, feito especificamente para mudanças de arquitetura. Você propõe mudanças no modelo C4, os revisores veem exatamente o que está sendo adicionado, modificado ou removido, e a mudança passa por um processo de aprovação antes de ser aplicada.

Isso traz governança para a evolução da arquitetura sem obrigar tudo a passar por arquivos YAML e diffs do Git.

Colaboração

Backstage

O Backstage é um portal web. Várias pessoas podem acessá-lo ao mesmo tempo, mas não há colaboração em tempo real sobre a arquitetura em si. Cada um consulta o catálogo por conta própria. Sem cursores ao vivo, sem indicadores de presença, sem edição simultânea.

Archyl

O Archyl oferece colaboração em tempo real nos diagramas C4:

• Cursores ao vivo mostrando onde os colegas estão no canvas
• Indicadores de presença mostrando quem está vendo o diagrama
• Acompanhamento de foco nos elementos, para você ver em quais elementos os colegas estão trabalhando
• Edição simultânea com resolução de conflitos

Isso vale tanto para os diagramas C4 de projeto quanto para a visão de Arquitetura Global.

Dados operacionais ao vivo

Uma das maiores surpresas de quem descobre o Archyl é o Marketplace. Documentação de arquitetura não é só diagrama estático: o Archyl se conecta às ferramentas que as suas equipes já usam e mostra dados ao vivo direto na sua arquitetura.

Backstage

Aqui, o ponto forte do Backstage é o ecossistema de plugins. Existem plugins para quase tudo: status de CI/CD, dashboards de monitoramento, controle de custos, status do Kubernetes e mais. Mas esses plugins vivem em páginas próprias dentro do portal. Eles não estão conectados à visão da arquitetura. Você vê o status de CI/CD de um serviço na página dele no catálogo, mas não no diagrama C4, onde esse serviço aparece no contexto de tudo de que ele depende.

Archyl

O Marketplace do Archyl oferece integrações que trazem dados ao vivo, em forma de widgets, direto para os painéis da sua arquitetura:

• CI/CD: status dos workflows do GitHub Actions, PRs abertos, alertas do Dependabot, varredura de segurança. Status dos pipelines do GitLab, merge requests, relatórios de vulnerabilidade, alertas SAST/DAST. Status das aplicações no Argo CD e acompanhamento de deploys.
• Observabilidade: dashboards do Datadog incorporados, consultas de métricas, status dos monitores. Consultas instantâneas e por intervalo no Prometheus, saúde dos targets. Rastreamento de erros com o Sentry.
• Qualidade de código: status do quality gate do SonarQube, métricas de código, issues, security hotspots e ratings.
• Gestão de incidentes: status de incidentes no PagerDuty, incidentes ativos, escalas de plantão, saúde dos serviços.

Os widgets se atualizam automaticamente e podem ser restritos a três níveis: a organização inteira, um projeto, ou um elemento C4 específico. Um container que representa o seu serviço de pagamentos pode mostrar o status do build no GitHub Actions, o quality gate do SonarQube, as métricas de saúde do Datadog e a escala de plantão do PagerDuty, tudo em um só lugar.

Isso transforma a documentação de arquitetura de uma referência estática em uma visão operacional viva. O diagrama não mostra só como o seu sistema é: mostra como ele está agora.

Além do básico

Mais algumas áreas em que as abordagens divergem:

Quando escolher cada um

Escolha o Backstage se você precisa de um developer portal unificado que reúna documentação, CI/CD, catálogo de serviços, gestão de custos e dezenas de outras frentes em uma única plataforma interna. A documentação de arquitetura é uma peça desse quebra-cabeça, e uma visão C4 de alto nível basta para as suas necessidades.

Escolha o Archyl se a documentação de arquitetura é uma preocupação central, mas você não quer abrir mão da visibilidade operacional para tê-la. O Archyl vai fundo no modelo C4 (os 4 níveis), em diagramas interativos, descoberta com IA, análise de impacto e governança de mudanças, enquanto as integrações do Marketplace trazem status de CI/CD, monitoramento, qualidade de código e dados de incidentes direto para a sua arquitetura. Você ganha ferramentas focadas em arquitetura sem perder o contexto operacional que o Backstage oferece com o seu ecossistema de plugins.

Os dois também podem coexistir. O Archyl cuida da modelagem detalhada da arquitetura, da análise e da visibilidade operacional ligada à arquitetura. O Backstage cuida da experiência de desenvolvimento mais ampla: onboarding, busca no catálogo, dashboards de custos e documentação geral. O modelo de arquitetura no Archyl pode orientar o que você documenta no catálogo de serviços do Backstage, sem que uma ferramenta substitua a outra.

Conclusão

O Backstage é um framework de plataforma que você monta a partir de plugins. Ele é poderoso, flexível e resolve o problema da fragmentação da experiência de desenvolvimento. Mas os seus recursos de documentação de arquitetura se limitam ao que os plugins C4 baseados no catálogo conseguem oferecer: em geral os níveis 1 e 2, visões estáticas, sem IA, sem análise de impacto, sem colaboração em tempo real nos diagramas.

O Archyl é uma ferramenta focada que vai fundo em arquitetura. Ele cobre o modelo C4 completo, descoberta com IA, análise de impacto, governança de mudanças e colaboração em tempo real, e se conecta às suas ferramentas de CI/CD, observabilidade, qualidade de código e incidentes, para que a sua arquitetura continue ancorada na realidade operacional. Ele não é um developer portal, mas é muito mais do que documentação estática.

A sua arquitetura merece mais do que uma entrada em um catálogo.

Novo no modelo C4? Comece pelo nosso guia do modelo C4. Já está modelando? Experimente a descoberta de arquitetura com IA para iniciar seu primeiro projeto a partir do código, ou conheça o Impact Radar para entender uma mudança antes de fazê-la.