Federation is EventCatalog at scale. Teams own their docs, services, and ADRs, and federate them into a central catalog people and AI agents can use.
EventCatalog already works as a central catalog. Plenty of teams keep architecture, services, and messages in one place, and that is a good way to run it.
Federation is EventCatalog at scale. Once you have that central catalog, some organizations want to go further. They want distributed documentation: teams own their own docs, and the organization still gets one catalog it can trust.
Teams keep owning their services, their information, their architecture decision records, and everything else, next to their code. They federate that into a central catalog. People keep working autonomously. The organization still gets a catalog that updates itself from what teams already write.
Today, I am happy to announce EventCatalog Federation v2.
Federation is now built into EventCatalog. It is composition: distributed catalogs, composed into a central view. Catalogs stay with the teams that own the work. The organization catalog lists those sources, validates ownership and relationships, and materializes one connected view for humans and agents.
This post is about how to think about that change. For the walkthrough, read the Federation docs.
Read the Federation product page
In December 2024 we shipped the first version of EventCatalog Federation as a plugin that cloned git repos and copied directories. Copies drifted, last-write-wins hid collisions, and you got a merged tree instead of a verified graph. v2 replaces that plugin model.
How to think about Federation v2
The useful mental model is three parts:
Distributed documentation. This is a pattern some teams choose after they already have a catalog, not a replacement for a single catalog. Teams own their services, their information, their architecture decision records, and everything else in their own EventCatalog, in their own repository, then federate that into the central catalog. Nothing changes for those teams. They do not install a federation plugin. They create a catalog the same way they always have.
The organization catalog composes. The organization catalog is still a catalog. That is the central information catalog. It lists the team catalogs it wants to combine, GitHub repositories or local paths. Four lines of config per source. It can own cross-cutting docs of its own. It composes team sources so the org view stays current for people and agents.
Every run is validated. Federation fetches the sources, checks ownership and relationships across the whole organization, and writes generated output. If two catalogs claim the same resource, the run fails and names both. Ambiguity is a modelling error, not something to render. The catalog that comes out of that run is the one people and agents can use.
The output goes to federated/. The normal EventCatalog development server or build then reads local resources and federated resources together.
Federation does not run automatically before dev, build, or generate. You run it on purpose:
npx eventcatalog federate
npm run build
eventcatalog federate fetches, validates, and materializes. npm run build renders the catalog that came out of that run.
Four lines of config, then one command
Imagine Acme. Payments, Orders, and Fulfillment each keep a catalog next to their code. The organization catalog points at them:
export default {
title: 'Acme Architecture',
federation: {
sources: [
{ id: 'acme/payments', source: 'github:acme/payments-catalog' },
{ id: 'acme/orders', source: 'github:acme/orders-catalog' },
{ id: 'acme/fulfillment', source: 'file:../fulfillment-catalog' },
],
},
};
Sources are GitHub (github:org/repo) or local (file:../path). Public or private GitHub. Local paths are there so you can try the whole loop on your machine before you wire up CI.
Then:
npx eventcatalog federate
That is the whole operator loop for this release. Configure sources, federate, then build.
Teams do not copy definitions between repositories. They reference other teams' events, commands, and services by ID. Federation resolves those pointers into one graph.
Fulfillment can consume an Orders event without owning a second copy of it:
---
id: warehouse-service
name: Warehouse Service
receives:
- id: order-completed
---
order-completed stays owned by Orders. Every consumer across the organization resolves to that one definition.
What is different from v1
v1 copied files. v2 indexes catalogs, validates the graph, hashes content, and generates federation output.
A few differences that change how you should model your architecture:
Reference, don't copy. v1 asked you to merge directories. v2 asks you to point at IDs. One definition, one owner.
Ownership fails closed. Every resource has exactly one owning catalog: the catalog that holds its files. If two catalogs claim the same resource, Federation stops and names them both. There is no silent last-write-wins.
Diagnostics you can tune. Collisions, missing resources, and version mismatches show up as lint-style diagnostics. Rules can be off, warn, or error with federation.rules, so you can start noisy and tighten in CI.
A lockfile. eventcatalog.lock records the commit and content digest of every source. Same inputs, same catalog.
Restore on failure. Runs are transactional. If a run fails, the previous output is restored. You do not ship a half-written catalog.
GitHub and local. You can federate from GitHub, or from a folder next to the central catalog while you develop.
The older @eventcatalog/generator-federation plugin is still the v1 model: clone a repo, copy configured directories, optionally override. v2 is built-in, and it is a different contract.
The organization catalog is still a catalog
A thing I want to be clear about: the central catalog is not an empty bucket.
It can own enterprise domains, organization-wide flows, and architecture decisions that span teams. Those local resources participate in the same ownership validation as federated ones. A central flow can point at a team-owned service. A team-owned service cannot quietly collide with something the central catalog already owns.
Generated content lands in federated/. Your own docs stay in the catalog. The development server and the build read both.
That is why composition is the right word. Distributed catalogs, composed into a central view.
This is still early
EventCatalog Federation is an Enterprise feature. The Federation docs cover the current workflow.
This is an initial working version for feedback. The core composition and validation are ready. Automatic build integration, source management commands, frozen lockfile installs, and local file watching may evolve as we learn how teams want to operate this.
If something feels missing, that is useful. Tell us what you expected Federation to do.
Try Federation v2
Upgrade EventCatalog, then federate:
npm install @eventcatalog/core@latest
npx eventcatalog federate
Start with the Federation page for the product view, then the Federation docs for how the workflow actually runs.
Thank you
Federation v2 is shaped by the teams who tried v1 on real catalogs, then told us where copies, last-write-wins, and clone-and-copy scripts ran out of road.
Every Discord conversation, GitHub issue, support call, and customer catalog helped make the contract smaller and stricter.
If you like EventCatalog, I would love a star on GitHub, and feel free to join our Discord community.
Thank you for being part of the journey.
Ready to get started?
npm install @eventcatalog/core@latest
npx eventcatalog federate
Read the Federation page | Read the Federation docs | Join Discord