The architecture catalog

The architecture catalog is one website that maps every product in the organization: what each service does, which events it publishes and consumes, which products it calls, who owns it, its runbook, which says what to do when it breaks, and the decisions behind it. Nobody draws the map by hand. Each repository publishes its own part every time a change merges, and the map rebuilds itself, so a team that depends on a product in another domain finds its current contracts and owners without asking anyone.

What it is

The map lives at catalog.projectairframe.dev, behind single sign-on, and everyone with an account in the organization can read it. It is built with EventCatalog, an open-source tool for documenting services and the events between them.

It is not the same thing as the catalog. The catalog is the repository of YAML files that says which products, teams and people exist, and every reconciler reads it. The architecture catalog is a website for people to read, and it takes its list of products from the catalog.

On the map:

each journey is a domain page and each domain a subdomain, with the context as a badge on each service;
each product is a service page: its overview, its API and event specifications, its owners, its criticality and data classification, its runbook, its postmortems, its documents and its decision records;
each event a product publishes has a page with its schema, its producer and its consumers;
each team and each person in the catalog has a page;
the platform has a domain of its own, with its repositories’ decision records and links to the handbook.

Airframe uses only the parts of EventCatalog that are free under the MIT license. Free-form pages belong to its commercial part, so the runbook, the postmortems and a product’s documents appear as sections of its service page.

How it is fed

Every product repository’s pipeline includes the platform’s catalog-publish component, and so do the catalog’s and those of the four platform repositories that keep decision records: landing-zone, control-plane, golden-path and operations. The component reads what the repository already holds and turns it into a fragment: the repository’s part of the map, as EventCatalog’s files plus a machine-readable index. For a product, that is:

catalog/service.md, the overview the page opens with, and catalog/product.yaml, the copy of the catalog entry, for the owners, the badges, the events and the calls;
contracts/, with the OpenAPI and AsyncAPI specifications and each event’s schema;
the runbook, postmortems/, docs/ and the decision records in docs/adr/.

On a merge request, the validate:fragment job generates the fragment with no credential and keeps it for the reviewer. It fails when the overview or the runbook is missing, a decision record is not named NNNN-slug.md, or a file is too large, and its message names the file and the rule.

On the protected main branch, after the merge, release:catalog publishes the fragment to a bucket under the repository’s own prefix, with the identity the repository already holds: a product publishes as its production apply identity, the catalog repository as platform-catalog@ and a platform repository as platform-docs@. A product’s identity and the catalog’s may write only under their own prefix, so no product can change another product’s part of the map. The four platform repositories share one identity, platform-docs@, whose grant covers the whole platform prefix, fragment/platform/: each publishes under its own folder there, and nothing stops one from writing another’s. The catalog repository publishes the journeys, domains, teams and people, and a platform repository its decision records.

A developer, or a coding agent, can see a product’s page before proposing it: airframe docs runs the same generator on a laptop and serves the page.

How the map is rebuilt

An aggregator, a Cloud Run job called eventcatalog-build in the lk-eventcatalog project, assembles the site. It runs right after each publication, started by the identity that published, which may start that job and do nothing else in the project, and every hour on a schedule, for anything a request missed.

Each run:

reads the catalog’s list of products, so a product removed from the catalog leaves the map even if its last fragment is still in the bucket;
fetches each repository’s latest fragment and checks it alone, skipping a broken one with its reasons in the run’s record, so the rest of the map still builds;
drops any reference to something no fragment defines, such as an event nobody has published yet;
builds the site with EventCatalog, uploads it as a new version and keeps the last three.

The site is a Cloud Run service behind the shared edge. It checks for a new version every minute; if it cannot read one, it keeps serving the last.

It follows main, not production

A fragment is published when a change merges, whether or not the deploy that follows succeeds. The map therefore shows what each repository’s main branch says, not what is running. The publication is allowed to fail, so a problem on the platform’s side never holds back a product’s deploy; the previous fragment stays on the map until the next merge.

Designed, not built

The catalog MCP server (designed). A small server that would let a coding agent ask the machine-readable index questions, such as who owns a topic or which decision a change would reverse, with the developer’s own credentials. The index exists today, published beside every build as airframe-index.json.
An issue for a broken fragment (designed). The aggregator would open an issue in the repository whose fragment it skipped; today the reasons are only in the run’s record and log.
An alert on a failed rebuild (designed).
Specifications generated from the code (designed). Today the template ships a starter OpenAPI file that each team keeps current by hand.

Where it lives

In the operations repository:

In the control-plane repository:

templates/catalog-publish/: the component that publishes a fragment

In the landing-zone repository:

docs/guides/architecture-catalog.md: from a repository to the map