El catálogo de arquitectura

El catálogo de arquitectura es un sitio web que mapea cada producto de la organización: qué hace cada servicio, qué eventos publica y consume, a qué productos llama, quién es su responsable, su runbook, que dice qué hacer cuando falla, y las decisiones que hay detrás. Nadie dibuja el mapa a mano. Cada repositorio publica su propia parte cada vez que un cambio se integra, y el mapa se reconstruye solo, así que un equipo que depende de un producto de otro dominio encuentra sus contratos y responsables actuales sin preguntarle a nadie.

Qué es

El mapa está en catalog.projectairframe.dev, detrás del inicio de sesión único, y cualquiera con una cuenta en la organización puede leerlo. Está construido con EventCatalog, una herramienta de código abierto para documentar servicios y los eventos entre ellos.

No es lo mismo que el catálogo. El catálogo es el repositorio de archivos YAML que dice qué productos, equipos y personas existen, y todos los reconciliadores lo leen. El catálogo de arquitectura es un sitio web para que lo lean las personas, y toma su lista de productos del catálogo.

En el mapa:

cada recorrido es una página de dominio y cada dominio un subdominio, con el contexto como una insignia en cada servicio;
cada producto es una página de servicio: su descripción general, sus especificaciones de API y de eventos, sus responsables, su criticidad y su clasificación de datos, su runbook, sus análisis de incidentes, sus documentos y sus registros de decisiones;
cada evento que publica un producto tiene una página con su esquema, su productor y sus consumidores;
cada equipo y cada persona del catálogo tiene una página;
la plataforma tiene un dominio propio, con los registros de decisiones de sus repositorios y enlaces al manual.

Airframe usa solo las partes de EventCatalog que son libres bajo la licencia MIT. Las páginas de formato libre pertenecen a su parte comercial, así que el runbook, los análisis de incidentes y los documentos de un producto aparecen como secciones de su página de servicio.

Cómo se alimenta

El pipeline de cada repositorio de producto incluye el componente catalog-publish de la plataforma, y también lo incluyen el del catálogo y los de los cuatro repositorios de la plataforma que llevan registros de decisiones: landing-zone, control-plane, golden-path y operations. El componente lee lo que el repositorio ya tiene y lo convierte en un fragmento: la parte del mapa que le toca al repositorio, como archivos de EventCatalog más un índice legible por máquinas. Para un producto, eso es:

catalog/service.md, la descripción general con la que abre la página, y catalog/product.yaml, la copia de la entrada del catálogo, para los responsables, las insignias, los eventos y las llamadas;
contracts/, con las especificaciones OpenAPI y AsyncAPI y el esquema de cada evento;
el runbook, postmortems/, docs/ y los registros de decisiones en docs/adr/.

En un merge request, el job validate:fragment genera el fragmento sin ninguna credencial y lo guarda para quien revisa. Falla cuando falta la descripción general o el runbook, cuando un registro de decisiones no se llama NNNN-slug.md o cuando un archivo es demasiado grande, y su mensaje nombra el archivo y la regla.

En la rama main protegida, después del merge, release:catalog publica el fragmento en un bucket bajo el prefijo propio del repositorio, con la identidad que el repositorio ya tiene: un producto publica con su identidad de apply de producción, el repositorio del catálogo como platform-catalog@ y un repositorio de la plataforma como platform-docs@. La identidad de un producto y la del catálogo pueden escribir solo bajo su propio prefijo, así que ningún producto puede cambiar la parte del mapa de otro producto. Los cuatro repositorios de la plataforma comparten una identidad, platform-docs@, cuyo permiso cubre todo el prefijo de la plataforma, fragment/platform/: cada uno publica bajo su propia carpeta allí, y nada impide que uno escriba la de otro. El repositorio del catálogo publica los recorridos, los dominios, los equipos y las personas, y un repositorio de la plataforma sus registros de decisiones.

Una persona que desarrolla, o un agente de código, puede ver la página de un producto antes de proponerla: airframe docs ejecuta el mismo generador en una laptop y sirve la página.

Cómo se reconstruye el mapa

Un agregador, un job de Cloud Run llamado eventcatalog-build en el proyecto lk-eventcatalog, arma el sitio. Corre justo después de cada publicación, iniciado por la identidad que publicó, que puede iniciar ese job y nada más en el proyecto, y cada hora según una programación, para lo que una solicitud haya perdido.

Cada ejecución:

lee la lista de productos del catálogo, así que un producto eliminado del catálogo sale del mapa aunque su último fragmento siga en el bucket;
trae el fragmento más reciente de cada repositorio y lo revisa por separado, y omite uno roto con sus razones en el registro de la ejecución, así que el resto del mapa se construye igual;
quita cualquier referencia a algo que ningún fragmento define, como un evento que nadie publicó todavía;
construye el sitio con EventCatalog, lo sube como una nueva versión y conserva las tres últimas.

El sitio es un servicio de Cloud Run detrás del borde compartido. Busca una nueva versión cada minuto; si no puede leerla, sigue sirviendo la última.

Sigue a main, no a producción

Un fragmento se publica cuando un cambio se integra, tenga éxito o no el despliegue que sigue. Por eso el mapa muestra lo que dice la rama main de cada repositorio, no lo que está corriendo. La publicación puede fallar sin detener nada, así que un problema del lado de la plataforma nunca retiene el despliegue de un producto; el fragmento anterior sigue en el mapa hasta el siguiente merge.

Diseñado, no construido

El servidor MCP del catálogo (diseñado). Un servidor pequeño que le permitiría a un agente de código hacerle preguntas al índice legible por máquinas, como quién es el responsable de un tema o qué decisión revertiría un cambio, con las propias credenciales de quien desarrolla. El índice ya existe, publicado junto a cada construcción como airframe-index.json.
Un issue por un fragmento roto (diseñado). El agregador abriría un issue en el repositorio cuyo fragmento omitió; hoy las razones están solo en el registro y en el log de la ejecución.
Una alerta por una reconstrucción fallida (diseñada).
Especificaciones generadas desde el código (diseñadas). Hoy la plantilla trae un archivo OpenAPI inicial que cada equipo mantiene al día a mano.

Dónde está

En el repositorio operations:

En el repositorio control-plane:

templates/catalog-publish/: el componente que publica un fragmento

En el repositorio landing-zone:

docs/guides/architecture-catalog.md: de un repositorio al mapa