Summary

August brought EventCatalog Federation v2, the new Architecture Graph, custom resource sidebars, stronger linting, channel maps, and plenty of fixes across the project.

Welcome to the monthly update for EventCatalog. In July we released EventCatalog v4 and introduced systems as a new way to document software architecture. In August we focused on what happens when that architecture grows across teams, repositories, and thousands of resources.

The headline is EventCatalog Federation v2, a new built-in workflow for composing team-owned catalogs into one verified organization catalog. We also shipped a catalog-wide Architecture Graph, custom sidebars for every resource, a major upgrade to the EventCatalog Linter, and plenty of improvements underneath.

We started the month on 4.3.4 and finished on 4.10.3.

• EventCatalog Federation v2, with the announcement and Federation docs
• See your whole architecture as a graph, then follow the Architecture Graph guide
• Build a sidebar around your readers with custom resource sidebars
• A much stronger EventCatalog Linter, covered in the Linter docs
• Channel maps for understanding message channels
• EventCatalog Scale now supports monthly subscriptions, with full details on the pricing page
• Other project improvements, with links to the relevant pull requests and issues, or browse every EventCatalog release

EventCatalog Federation v2

EventCatalog works well as a central catalog, but large organizations often want teams to own their architecture documentation next to their code while still giving everyone one place to explore the wider system.

In August we released EventCatalog Federation v2.

Federation is now built into EventCatalog. An organization catalog lists the team catalogs it wants to compose, then one command fetches those sources, validates ownership and relationships across them, and materializes a connected view for people and AI agents.

eventcatalog.config.js

export default {
  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' },
    ],
  },
};

Then run:

npx eventcatalog federate

The important change from the first version is the contract. Federation v1 cloned repositories and copied configured directories. Federation v2 indexes catalogs and resolves their architecture graph. Teams reference resources owned by other teams instead of copying them, and collisions fail closed instead of being hidden by last-write-wins behavior.

Read the EventCatalog Federation docs

Each run also writes an eventcatalog.lock file with the resolved source state, uses a content-addressed cache, and restores the previous output if a run fails. Diagnostics for duplicate ownership, missing resources, unresolved versions, type conflicts, and asset collisions can be configured as off, warn, or error.

Federation can pull from GitHub or local folders, which means you can test the whole workflow on your machine before wiring it into CI. Team-owned custom components and public assets can come across too, while central catalog components still take precedence.

This is the first working version of the new model and we are looking for feedback. You can read more in the Federation v2 announcement or follow the Federation guide to try it.

See your whole architecture as a graph

Systems and context maps give you deliberate, curated views of an architecture. Sometimes you need the opposite: one map that starts with everything and lets you explore from there.

EventCatalog 4.5.0 introduced the new Architecture Graph, a catalog-wide force-directed graph of your domains, systems, services, agents, messages, flows, entities, containers, data products, teams, and the relationships between them.

Read the Architecture Graph guide

You can search for any resource, click it to focus on its neighbourhood, change how many hops you want to see, and switch lenses to group the graph around domains, systems, owners, or resource types. Double-clicking a node opens its documentation.

The graph renders to a single canvas and keeps its wire format compact, so it is designed to stay responsive even when a catalog contains thousands of resources. It is opt-in while in beta:

eventcatalog.config.js

export default {
  visualiser: {
    architectureGraph: {
      enabled: true,
    },
  },
};

At the end of the month we also added the <ArchitectureGraph/> component, so you can embed a focused view directly into a domain, system, service, message, or custom documentation page.

<ArchitectureGraph depth="3" lens="messages" />

The embedded graph starts from the resource being documented. Readers can explore locally, then open the same state full screen when they need more room. The component works even if the full-page graph is not enabled.

Build a sidebar around your readers

Generated resource sidebars are useful because they stay up to date automatically. But the most useful order for EventCatalog is not always the most useful order for your readers.

EventCatalog 4.10.0 adds custom resource sidebars. Add a sidebar.json next to any resource's index.mdx and you can define the navigation for that resource yourself.

Organize each resource around the guides, contracts, and architecture your readers need

domains/Payments/sidebar.json

{
  "sections": [
    { "section": "$quick-reference", "title": "Start here" },
    {
      "title": "Guides",
      "pages": ["[[doc|guides/onboarding]]"]
    },
    { "section": "$services", "title": "APIs and workers" },
    { "section": "$domain-events", "title": "Integration contracts" },
    { "section": "$decision-records", "collapsed": true }
  ]
}

The $sections remain live as your catalog changes, while custom groups can mix documentation, specifications, schemas, resource references, and normal links. Groups can be nested or collapsed, and versioned resources inherit the sidebar from the resource folder unless they define their own.

If a token, document, specification, or schema cannot be resolved, the build fails with the file and valid options. That makes a custom sidebar safe to maintain rather than another navigation file that silently drifts.

A much stronger EventCatalog Linter

The EventCatalog Linter received one of its largest upgrades so far in August.

New rules now catch unknown frontmatter fields, unrecognised Markdown files, and file references that point at missing schemas, specifications, data product contracts, or public icons. Misspelled fields include suggestions, and x- custom properties continue to work as expected.

Findings now include the exact line and column, version ranges behave the same way as EventCatalog core, and missing resources are reported separately from references to versions that do not exist.

npx @eventcatalog/linter --init

The new --init command creates a fully commented .eventcatalogrc.js with every rule and its default severity. We also added --quiet, --max-warnings, and --no-color, fixed the checked-file summary, and made CI output quieter and easier to scan.

Channel maps

Channels now have their own architecture maps.

A big thank you to Jonas Lagoni, who contributed this feature in #2756.

A channel map shows the producers and messages that publish into the channel, the services and agents that consume from it, and the channels it routes to or receives routes from. Routed chains remain connected all the way through, so you can follow how a message enters one channel and reaches a consumer through another.

You can add <NodeGraph /> to a channel page, or open the Architecture → Map link in its sidebar when the visualiser is enabled.

EventCatalog Scale now supports monthly subscriptions

EventCatalog Scale is now available month-to-month alongside annual billing, giving teams more flexibility to get started and cancel at any time.

Other project improvements

• Customizable sidebars for any resource using sidebar.json (#2832)
• New <ArchitectureGraph/> component for resource and custom documentation pages (#2834)
• New linter rules, line and column reporting, accurate summaries, and --init configuration scaffolding (#2831)
• Support for V1, V2, and other V-prefixed integer resource versions across lookup, comparison, federation, and snapshots (#2815)
• Ubiquitous language terms now support edit URLs and appear in indexed search (#2820, #2802)
• Domain resource pages now include every directly attached resource, including subdomains, systems, agents, and data products (#2769)
• AsyncAPI parser errors now render on the page instead of leaving a blank screen (#2777)
• AsyncAPI generator now preserves shared references when saving parsed specification files (#445)
• OpenAPI and AsyncAPI generators now escape angle brackets in descriptions so generated MDX continues to build (#447)
• Historical message versions now show their version-specific producers and consumers (#2787, #2805)
• Fixed container context-menu links opening entity URLs instead of container URLs (#2804, #2809)
• Fixed a Windows development-server crash caused by backslashes in watched project paths (#2806)
• Fixed LikeC4 diagrams in Vite development mode (#2823)
• Fixed domain-owned entities appearing as external resources in entity maps (#2825)
• Fixed embedded Architecture Graphs in static builds and missing domain System Diagram pages (#2839)
• Updated vulnerable dependencies and bumped Astro and its integrations through 7.2.8 (#2771, #2818)

Thanks

Thanks to everyone who contributed to EventCatalog this month by opening issues, reporting bugs, and suggesting features, including Jonas Lagoni, Lucas Chabalier, Alex Dunne, Xavier Gouley, Ondrej Musil, and many more.

The detailed reports and fixes from the community helped us make the new v4 foundation more reliable while we kept building on it.

What's coming in September?

A few things we're working on:

• Notifications for breaking changes
• Better ways to capture breaking changes
• Improvements to our Code-to-Docs workflows
• Introducing community calls for EventCatalog

If you have any questions or want to join our community exploring EventCatalog and event-driven architecture feel free to join us!

Until next time!, Dave