EventCatalog – Document Event-Driven Architectures

TL;DR

TL;DR: EventCatalog is an open-source documentation tool for event-driven systems — document domains, services, events, and schemas with AI-powered discovery, a schema explorer, and 15+ generators for AsyncAPI, OpenAPI, Kafka, and more.

Source and Accuracy Notes

⚠️ This section is MANDATORY. All links must be verified from actual source, not guessed.

• Project page: eventcatalog.dev
• Source repository: github.com/event-catalog/eventcatalog
• License: MIT (verified via LICENSE file in main branch)
• Latest release: v0.6.14 (verified via GitHub Releases API)
• HN launch thread: news.ycombinator.com/item?id=30606114
• Stars: 2,771 (verified via GitHub API)

What Is EventCatalog?

EventCatalog describes itself as “the discovery and governance layer for event-driven systems.” Its README opens with:

“The open source documentation tool for software architectures.”

The core pitch: most teams document APIs with Swagger/OpenAPI but leave their event contracts undocumented. Events drift, schemas break across services, and nobody has a single source of truth. EventCatalog fills that gap.

Key capabilities from the README:

• Document architecture — domains, services, commands, events, and schemas
• AI-powered discovery — ask questions about your architecture in natural language; ships with an MCP server
• Schema explorer — search across OpenAPI, AsyncAPI, Protobuf, JSON Schema, Avro, and more
• Schema fields — find any property across your entire catalog and trace how fields are used across services
• 15+ generators — auto-generate from AsyncAPI, OpenAPI, Kafka, Confluent, AWS EventBridge, and more
• Versioning — semantic versioning for events, commands, and services
• Customizable — themes, MDX components, configurable layouts
• Enterprise ready — OAuth2, RBAC, schema governance, breaking change detection

The project reports 40,000+ catalogs created and 69 contributors.

Setup Workflow

Step 1: Create a new catalog

npx @eventcatalog/create-eventcatalog@latest my-catalog

This scaffolds a new project and starts the dev server at http://localhost:3000.

Step 2: Add your first service

From the dashboard, navigate to Services → Add Service. Fill in the service name, version, and owner. Each service can have a Markdown description, associated events, and links to running instances.

Step 3: Register an event

Under Events, create an event with a name, version, and schema. EventCatalog accepts schemas in JSON Schema, Avro, Protobuf, or AsyncAPI format. The schema is stored as a versioned file in the catalog.

Step 4: Connect a generator (optional)

If your events are defined in AsyncAPI or Kafka schema registries, you can auto-import them:

# Import from AsyncAPI
npx @eventcatalog/core import-asyncapi --file ./asyncapi.yaml

# Import from Confluent Schema Registry
npx @eventcatalog/core import-confluent --url http://localhost:8081

Step 5: Enable AI discovery (optional)

EventCatalog includes a built-in AI chat that reads your catalog. Configuration requires an OpenAI or Anthropic API key in your environment:

OPENAI_API_KEY=sk-... npm run start

The MCP server also exposes catalog queries to external AI agents, letting them ask questions like “which services emit UserCreated events?” without reading the source directly.

Deeper Analysis

Schema governance

EventCatalog tracks schema evolution across versions. When a field is removed or its type changes, the breaking change detector flags it and surfaces it in the diff view. This is useful for teams enforcing contract-first development.

Generators

The 15+ generators cover the major event-driven ecosystems:

| Generator | Source format | |---|---| | AsyncAPI | AsyncAPI 2.x | | OpenAPI | OpenAPI 3.x | | Kafka | Confluent Schema Registry | | AWS EventBridge | CloudFormation / JSON | | Protobuf | .proto files | | JSON Schema | Standalone .json files | | Avro | Confluent Avro schema |

Each generator produces a versioned event definition in the catalog, keeping the source of truth in the repo rather than a separate docs site.

Enterprise features

OAuth2 and RBAC are available for teams that want to restrict who can edit versus read the catalog. The README explicitly mentions these as enterprise-ready features, differentiating it from pure open-source documentation tools like Swagger UI or Mintlify.

Practical Evaluation Checklist

• Can I run it locally in under 5 minutes? Yes — one npx command, no backend required for the core catalog.
• Does it handle multiple schema formats? Yes — OpenAPI, AsyncAPI, Protobuf, JSON Schema, Avro.
• Is the AI chat actually useful or just a novelty? The MCP server is the more practical feature — it lets AI agents query the catalog programmatically rather than relying on a chat UI.
• How does it compare to documenting in Confluence or Notion? EventCatalog is schema-aware and version-aware. A Notion page does not track breaking changes or let you filter all events by a specific field name across the org.
• What breaks if the team stops maintaining it? The catalog is Markdown/MDX files in a Git repo — fully portable, no vendor lock-in.

Security Notes

• API keys for AI features are set via environment variables and never stored in the catalog files.
• OAuth2 support means enterprise teams can integrate with their identity provider.
• The catalog itself is a static site by default — attack surface is limited to the build pipeline.

FAQ

Q: Do I need to define events in a specific format to use EventCatalog? A: No. You can create events manually through the UI with freeform Markdown, or import them in bulk from AsyncAPI, Kafka, Confluent, AWS EventBridge, Protobuf, or JSON Schema files.

Q: How is this different from Mintlify or Docusaurus for API docs? A: Both Mintlify and Docusaurus are general-purpose documentation sites. EventCatalog is purpose-built for event contracts — it understands events, schemas, and the relationships between services. The schema explorer, breaking change detection, and event-specific generators are not features those tools provide.

Q: Can non-technical stakeholders view the catalog? A: Yes. EventCatalog generates a static site with a read-only UI. You can deploy it to any static host (Cloudflare Pages, Vercel, S3) and share a URL without giving edit access.

Q: Does it work with serverless event sources like EventBridge? A: Yes. EventCatalog has an AWS EventBridge generator that imports event definitions from CloudFormation or JSON schemas.

Q: Is the AI chat feature free? A: The AI chat requires an OpenAI or Anthropic API key. There is no managed AI service — you bring your own key and pay for usage directly with the provider.

Conclusion

EventCatalog solves a real gap in event-driven architectures: the lack of a shared, machine-readable record of what events exist, what schemas they use, and which services own them. With 15+ generators, AI-powered discovery, schema governance, and a fully Git-backed storage model, it is more capable than ad-hoc Wiki pages or stale PDF diagrams.

If your team runs Kafka, AWS EventBridge, or any message-bus architecture and is tired of “just check the producer code,” EventCatalog is worth 10 minutes to try. Start with npx @eventcatalog/create-eventcatalog@latest and import your first AsyncAPI spec.