O catálogo de arquitetura

O catálogo de arquitetura é um site que mapeia cada produto da organização: o que cada serviço faz, quais eventos publica e consome, quais produtos chama, quem é responsável por ele, seu runbook, que diz o que fazer quando ele quebra, e as decisões por trás dele. Ninguém desenha o mapa à mão. Cada repositório publica a sua própria parte toda vez que uma mudança é integrada, e o mapa se reconstrói sozinho, então uma equipe que depende de um produto de outro domínio encontra os contratos e os responsáveis atuais dele sem perguntar a ninguém.

O que ele é

O mapa fica em catalog.projectairframe.dev, atrás do login único, e qualquer pessoa com uma conta na organização pode lê-lo. Ele é construído com o EventCatalog, uma ferramenta de código aberto para documentar serviços e os eventos entre eles.

Ele não é a mesma coisa que o catálogo. O catálogo é o repositório de arquivos YAML que diz quais produtos, equipes e pessoas existem, e todo reconciliador o lê. O catálogo de arquitetura é um site para pessoas lerem, e ele tira a sua lista de produtos do catálogo.

No mapa:

cada jornada é uma página de domínio e cada domínio um subdomínio, com o contexto como um selo em cada serviço;
cada produto é uma página de serviço: sua visão geral, suas especificações de API e de eventos, seus responsáveis, sua criticidade e sua classificação de dados, seu runbook, suas análises de incidentes, seus documentos e seus registros de decisão;
cada evento que um produto publica tem uma página com o seu esquema, o seu produtor e os seus consumidores;
cada equipe e cada pessoa do catálogo tem uma página;
a plataforma tem um domínio próprio, com os registros de decisão dos seus repositórios e links para o manual.

O Airframe usa só as partes do EventCatalog que são livres sob a licença MIT. As páginas de formato livre pertencem à sua parte comercial, então o runbook, as análises de incidentes e os documentos de um produto aparecem como seções da sua página de serviço.

Como ele é alimentado

O pipeline de cada repositório de produto inclui o componente catalog-publish da plataforma, e o mesmo fazem o do catálogo e os dos quatro repositórios da plataforma que mantêm registros de decisão: landing-zone, control-plane, golden-path e operations. O componente lê o que o repositório já tem e transforma isso em um fragmento: a parte do mapa que cabe ao repositório, como arquivos do EventCatalog mais um índice legível por máquina. Para um produto, isso é:

catalog/service.md, a visão geral com que a página abre, e catalog/product.yaml, a cópia da entrada do catálogo, para os responsáveis, os selos, os eventos e as chamadas;
contracts/, com as especificações OpenAPI e AsyncAPI e o esquema de cada evento;
o runbook, postmortems/, docs/ e os registros de decisão em docs/adr/.

Em um merge request, o job validate:fragment gera o fragmento sem nenhuma credencial e o guarda para quem revisa. Ele falha quando falta a visão geral ou o runbook, quando um registro de decisão não se chama NNNN-slug.md ou quando um arquivo é grande demais, e a sua mensagem nomeia o arquivo e a regra.

Na branch main protegida, depois do merge, release:catalog publica o fragmento em um bucket sob o prefixo próprio do repositório, com a identidade que o repositório já tem: um produto publica com a sua identidade de apply de produção, o repositório do catálogo como platform-catalog@ e um repositório da plataforma como platform-docs@. A identidade de um produto e a do catálogo só podem escrever sob o seu próprio prefixo, então nenhum produto consegue mudar a parte do mapa de outro produto. Os quatro repositórios da plataforma compartilham uma identidade, platform-docs@, cuja permissão cobre todo o prefixo da plataforma, fragment/platform/: cada um publica sob a sua própria pasta ali, e nada impede que um escreva a de outro. O repositório do catálogo publica as jornadas, os domínios, as equipes e as pessoas, e um repositório da plataforma os seus registros de decisão.

Uma pessoa desenvolvedora, ou um agente de código, pode ver a página de um produto antes de propô-la: airframe docs roda o mesmo gerador em um notebook e serve a página.

Como o mapa é reconstruído

Um agregador, um job do Cloud Run chamado eventcatalog-build no projeto lk-eventcatalog, monta o site. Ele roda logo depois de cada publicação, iniciado pela identidade que publicou, que pode iniciar esse job e nada mais no projeto, e a cada hora por um agendamento, para o que uma solicitação tenha perdido.

Cada execução:

lê a lista de produtos do catálogo, então um produto removido do catálogo sai do mapa mesmo que o seu último fragmento ainda esteja no bucket;
busca o fragmento mais recente de cada repositório e o confere sozinho, pulando um quebrado com os motivos no registro da execução, então o resto do mapa é construído mesmo assim;
tira qualquer referência a algo que nenhum fragmento define, como um evento que ninguém publicou ainda;
constrói o site com o EventCatalog, envia-o como uma nova versão e mantém as três últimas.

O site é um serviço do Cloud Run atrás da borda compartilhada. Ele procura uma nova versão a cada minuto; se não consegue lê-la, continua servindo a última.

Ele segue a main, não a produção

Um fragmento é publicado quando uma mudança é integrada, quer a implantação que vem depois dê certo ou não. Por isso o mapa mostra o que a branch main de cada repositório diz, não o que está rodando. A publicação pode falhar sem segurar nada, então um problema do lado da plataforma nunca retém a implantação de um produto; o fragmento anterior continua no mapa até o próximo merge.

Projetado, não construído

O servidor MCP do catálogo (projetado). Um servidor pequeno que permitiria a um agente de código fazer perguntas ao índice legível por máquina, como quem é responsável por um tópico ou qual decisão uma mudança reverteria, com as próprias credenciais de quem desenvolve. O índice já existe, publicado ao lado de cada construção como airframe-index.json.
Um issue para um fragmento quebrado (projetado). O agregador abriria um issue no repositório cujo fragmento ele pulou; hoje os motivos estão só no registro e no log da execução.
Um alerta para uma reconstrução que falhou (projetado).
Especificações geradas a partir do código (projetadas). Hoje o template traz um arquivo OpenAPI inicial que cada equipe mantém em dia à mão.

Onde fica

No repositório operations:

No repositório control-plane:

templates/catalog-publish/: o componente que publica um fragmento

No repositório landing-zone:

docs/guides/architecture-catalog.md: de um repositório ao mapa