Your architecture is changing. Do you know about it?

As event-driven architectures scale, an invisible problem emerges: who is producing what, and who is consuming it? A service starts consuming your OrderPlaced event. No ticket. No Slack message. No email. You find out weeks later when something breaks downstream.

At scale, you need governance over these relationships. You need to know when dependencies change, who is affected, and ideally, before it reaches production.

Architecture changes are invisible

In event-driven systems, things change constantly. New consumers appear. Producers get decommissioned. Messages get deprecated or versioned. Schemas evolve. Dependencies shift across teams, repos, and time.

The problem is visibility. When a new service starts consuming your event, who gets told? When a producer goes away, do the teams depending on that message get a warning? When a schema changes, do downstream consumers know? Most of the time, no. Teams find out after something breaks, not before.

Service owners have no way to see who depends on their messages. Platform teams trace relationships manually after incidents. Breaking changes land in production because no one was watching the dependency graph.

Architecture Change Detection is our first step toward solving this. Starting with producer and consumer relationship changes, with more detection capabilities coming soon.

Introducing Architecture Change Detection

Architecture Change Detection is a new feature that turns your catalog into an active monitoring system. It compares your EventCatalog across git branches, detects when services start or stop producing or consuming messages, and notifies your teams automatically.

You define rules. The tool watches. Your teams stay informed.

When you'd use it

This feature is designed for teams where the cost of a missed architecture change is high.

Service owners who want to know the moment someone starts depending on their messages. Platform teams who need to enforce governance and catch breaking changes before a PR merges. Operations teams who want an audit trail of every dependency change across the catalog. If any of those sound familiar, this is for you.

How it works

You define governance rules in a governance.yaml file at the root of your catalog. Each rule specifies what to watch, what conditions to trigger on, and where to send notifications.

governance.yaml

rules:
  - name: notify-consumer-changes
    when:
      - consumer_added
      - consumer_removed
    resources:
      - produces:OrdersService
    actions:
      - type: console
      - type: webhook
        url: $SLACK_WEBHOOK_URL

This rule watches every message that OrdersService produces. When any service starts or stops consuming one of those messages, it fires. Notifications go to the console and to a Slack webhook.

Triggers

To start, rules respond to four triggers, with more coming soon:

• consumer_added: a service started consuming a message
• consumer_removed: a service stopped consuming a message
• producer_added: a new service started producing a message
• producer_removed: a service stopped producing a message

Resources

The resources field controls what to watch. You can be broad or narrow:

• *: everything in the catalog
• message:OrderPlaced: a specific message
• service:NotificationService: a specific service (as consumer or producer)
• produces:OrdersService: all messages that OrdersService produces
• consumes:PaymentService: all messages that PaymentService consumes

Actions

When a rule fires, it can trigger two action types. console prints the change to the terminal. webhook sends a POST request in CloudEvents 1.0 format to any URL, Slack, PagerDuty, or any other endpoint that accepts a webhook.

Webhook payloads include the service involved with its owners, the message involved with its type (event, command, or query), and a human-readable summary of what changed.

Running the check

Run the check against any two branches:

npx @eventcatalog/cli governance check \
  --base main \
  --target feature/new-consumer

EventCatalog compares the two branches, finds the architectural differences, and evaluates them against your rules. Changes that match a rule trigger the configured actions.

Integrating with CI/CD

The real power comes from running this check automatically on every pull request. Add it to your GitHub Actions workflow to catch changes before they merge:

.github/workflows/governance.yaml

name: EventCatalog Governance
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
      - run: |
          npx @eventcatalog/cli governance check \
            --base main \
            --target ${{ github.head_ref }} \
            --status proposed
        env:
          EVENTCATALOG_SCALE_LICENSE_KEY: ${{ secrets.EVENTCATALOG_SCALE_LICENSE_KEY }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

The --status proposed flag marks webhook payloads with the PR lifecycle stage. When a PR is approved and merged, you can run the check again with --status approved to notify teams that the change is confirmed.

Recipes to get you started

We've put together a handful of ready-to-use configurations for common scenarios:

• Alert when a message gets a new consumer, so you know when teams start depending on your events
• Alert when anyone consumes any message your service produces, giving service owners full downstream visibility
• Detect when an upstream producer disappears, catching breaking changes before they affect your service
• Track all changes across the catalog, for audit logs or a central ops channel
• Monitor all changes for a specific service, regardless of which message is affected

Each recipe includes a copy-paste governance.yaml configuration. Check out the full list in the Recipes documentation.

Getting started

Architecture Change Detection is available on the Scale plan. Not on Scale yet? Start a 14-day free trial.

Once you have a license key, set it as the EVENTCATALOG_SCALE_LICENSE_KEY environment variable, create a governance.yaml file at the root of your catalog, and run your first check:

npx @eventcatalog/cli governance check --base main --target HEAD

That's it. You'll see the detected changes printed to the console, and any matching rules will fire their configured actions.

Summary

Architecture Change Detection solves a real problem in event-driven systems: the gap between what changes and who gets notified. Define rules once, run checks in CI, and your teams stay informed automatically.

Your catalog becomes a governance layer, not just documentation.

What's next

Producer and consumer detection is just the beginning. We're working on expanding Architecture Change Detection to cover more of the changes that matter to your teams:

• Schema change detection: know when message schemas evolve across versions
• Breaking change detection: catch backward-incompatible schema changes before they affect consumers
• Message deprecation alerts: get notified when messages are deprecated so dependent teams can plan ahead
• Version lifecycle tracking: detect when resources are versioned and track the upgrade path

If you have ideas for what you'd like to detect in your catalog, let us know on Discord or raise an issue on GitHub.

Read the full Architecture Change Detection documentation for complete configuration options and recipes.