# How EventCatalog Federation works

Copy as Markdown[View as Markdown](/docs/federation/explanation/how-it-works.md)

***

`EventCatalog Enterprise Feature`

EventCatalog Federation is a build-time composition process.

It reads independently owned catalogs, converts them into a common index, validates the combined graph, and writes generated catalog files that the normal EventCatalog application can render.

## The three-stage pipeline[​](#the-three-stage-pipeline "Direct link to The three-stage pipeline")

### Index[​](#index "Direct link to Index")

Each source catalog is described as facts:

* Resource IDs, types, and versions
* Resource ownership and relationships
* Content paths and hashes
* Schemas and specifications
* Sidecar documentation
* Public assets and custom components

Federation operates on EventCatalog's existing files and frontmatter. Teams do not maintain a second federation-specific resource definition.

### Resolve[​](#resolve "Direct link to Resolve")

Federation combines the indexes into one graph. The resolver:

* Connects relationships across source boundaries
* Selects resource versions for relationship pointers
* Detects multiple owners for one resource ID
* Detects conflicting resource types
* Detects relationship type mismatches
* Identifies missing resources and unavailable versions
* Chooses a deterministic winner for remote asset collisions

The central catalog's local resources participate in ownership validation. A local flow or architecture decision can point to federated resources, while a local resource can also conflict with a remote owner.

### Hydrate[​](#hydrate "Direct link to Hydrate")

After validation succeeds, Federation fetches the selected resource files and writes them under `federated/`.

Schemas, specifications, sidecars, public assets, and custom components travel with their owning resources. Content hashes are checked before files are accepted.

The normal EventCatalog build then reads local and federated content together.

## How sources are acquired[​](#how-sources-are-acquired "Direct link to How sources are acquired")

Federation currently supports GitHub and local filesystem sources.

A GitHub source can publish `catalog.index.json`. If the file exists, Federation checks its source ID and uses it. If the file does not exist, Federation creates an index from a temporary checkout.

A filesystem source is indexed directly. Its revision is derived from the indexed content so the completed run can record which local state it used.

After source acquisition, both source types use the same validation, hydration, caching, asset, and lockfile behavior.

## Federation materializes files[​](#federation-materializes-files "Direct link to Federation materializes files")

Federation does not make live requests to team catalogs when somebody opens the organization site.

The generated files are a local representation of the last successful federation run:

```
central-catalog/
├── domains/                  # centrally owned resources
├── federated/                # generated source resources
├── public/                   # central and managed remote assets
├── eventcatalog.lock         # completed-run receipt and managed asset state
└── .eventcatalog-cache/      # reusable verified content
```

This means the organization catalog can be built and deployed through the same process as any other EventCatalog after Federation completes.

## Failed updates preserve the previous view[​](#failed-updates-preserve-the-previous-view "Direct link to Failed updates preserve the previous view")

Federation validates the graph before hydration. Output changes are staged, and the lockfile is written after the generated resources and public assets are composed.

If a normal update fails while installing new output, Federation attempts to restore the previous `federated/` directory and affected public assets. A bad source update should not replace the last successful organization view with partial output.

## Federation is explicit[​](#federation-is-explicit "Direct link to Federation is explicit")

The federation command and EventCatalog build are separate:

```
npx eventcatalog federate
npm run build
```

This keeps source acquisition and graph validation visible in local workflows and CI. The current release does not automatically federate before `dev`, `build`, or `generate`.

## Related guides[​](#related-guides "Direct link to Related guides")

* [Ownership and cross-catalog references](/docs/federation/explanation/ownership-and-references.md)
* [Lockfile and cache](/docs/federation/explanation/lockfile-and-cache.md)
* [Generated output reference](/docs/federation/reference/generated-output.md)