Skip to main content

Adoption playbook

How teams use EventCatalog.

The question we hear most from architects is how other teams run it. This is the pattern we see work, from the first service to a catalog the whole organisation contributes to.

Start with one service Talk through your rollout

Start small, then let it grow.

The catalogs that stick grow out of one useful area, not a big-bang documentation project.

  1. 01

    Decide what you want it for

    EventCatalog fits a lot of workflows, so start by naming the problem. Most teams pick one or two things that hurt today, like finding who owns a message or knowing what a change will break. That choice decides what you document first.

    What should it do for you first?

    Find what exists and who owns itCheck the impact of a changeOnboard new engineersGovern schemas and standardsGive AI agents contextPlan future architecture
  2. 02

    Start with one service or domain

    Don’t try to document the whole organisation on day one. Pick one service, or the domain people ask about most, and document it properly: its owner, the messages it sends and receives, and its specs.

    Learn by building a small catalog

    DomainPayments

    ServicePayment ServiceOwned by Payments team
    OpenAPI2 events1 command
    Refund Service
    Fraud Service
    Ledger Service
  3. 03

    Deploy it and get feedback

    Put it in front of a few teams early, even if it only covers one area. The questions they ask show you what is missing and what to document next.

    Deploy your catalog

    Your next three pages to write

  4. 04

    Automate what can be automated

    Once the shape is right, pull the facts in automatically. Generators read your OpenAPI and AsyncAPI specs and your schema registries across the organisation, so services, messages and schemas stay current without anyone maintaining them by hand.

    See the integrations
    Orders APIOpenAPISynced
    Order eventsAsyncAPISynced
    Schema registry48 schemasSynced

    Rebuilt in CI whenever a spec changes

  5. 05

    Give the catalog an owner

    Catalogs that last have an owner. Usually a central architecture or platform team owns the catalog itself: the structure, the standards and the deployment. They don’t write everything. They make it easy for everyone else to contribute.

    Teams and ownership
    Architecture teamOwns the catalog

    Sets the structure: domains, naming and templates

    Runs the automation and the deployment

    Reviews contributions from other teams

Automation for the facts. People for the meaning.

Step six is where the value compounds. Every team contributes in two ways: automation keeps what can be generated in sync, and pull requests add what only people know.

Automated

Pull requests from teams

OpenAPI specsServices and APIs
AsyncAPI specsMessages and channels
Schema registriesEvery schema version
EventCatalog AgentDocs updated on code changes
Checkout flowPayments team
What OrderPlaced meansOrders team
Use events for paymentsArchitecture team
Fulfilment glossaryFulfilment team
Your catalog
Services and APIssynced
Messages and channelssynced
Schemassynced
Business flowswritten
What schemas meanwritten
Decisions (ADRs)written
Domain languagewritten
Owned by the architecture team
Automated

What automation keeps current

Services, APIs, messages, channels and schema versions, generated from the specs and registries teams already maintain. The EventCatalog Agent updates the docs when code changes.

Integrations
Pull requests

What people add

Business flows, what a schema means to the business, architecture decisions and domain language. Teams open a pull request like any other change, and the catalog owners review it.

How a catalog is structured

Where to go from here.

Learn the model firstAn 11-chapter course that builds a small catalog step by step.Automate from your specsOpenAPI, AsyncAPI, schema registries and the EventCatalog Agent.One catalog or many?Let teams run their own catalogs and federate them into one view.

Plan your rollout with us.

Tell us how your teams work and we’ll help you choose where to start, what to automate and who should own it.

Book a call Start with one service