EventCatalog: a documentation tool that treats domains, services and messages as first-class resources
Documentation tool built for software architecture. Document your domains, services, events and schemas — for your teams and your AI agents.
At a glance
- What is it?
- EventCatalog is an Astro and React application that stores architecture documentation as versioned resources and generates a browsable catalog from them. The core judgement: it fits event-driven and service-oriented teams that will commit to maintaining the resource files, and it is the wrong tool for anyone who wants a wiki that writes itself.
- Who is it for?
- Adopt EventCatalog if your architecture is already expressed as domains, services and messages and you are willing to keep those resource files in version control alongside the code they describe. Do not adopt it if you want a zero-maintenance wiki, if your system is a single deployable with no meaningful message contracts, or if you cannot accept the MIT plus commercial licence split.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem EventCatalog targets: architecture knowledge that lives nowhere in particular
Most teams already have the raw material for architecture documentation. It is spread across AsyncAPI and OpenAPI files, Protobuf definitions, Kafka topic configs, and the heads of the two engineers who built the thing. What is missing is a single place where a domain, the services inside it, the messages those services publish and consume, and the schemas behind those messages are modelled as connected objects rather than as prose. The README frames the project as a documentation tool designed for software architecture, not generic pages, and that distinction is the whole pitch. A generic wiki page about the Orders service goes stale silently. A resource file that declares the Orders service, its version, its owners and the events it emits can be validated, generated and diffed. EventCatalog is aimed at teams running event-driven or service-oriented systems where the message contracts are the architecture. If your system is a monolith with an internal module graph, the modelling vocabulary here (domains, services, messages, schemas, flows) will feel like a costume you are putting on rather than a description of what you have.
How the catalog is put together: Astro, React and file-backed resources
The repository lists four packages. @eventcatalog/core is the main catalog application, built with Astro and React. @eventcatalog/sdk is a Node.js SDK for programmatic catalog management. @eventcatalog/create-eventcatalog is the CLI scaffolding tool. @eventcatalog/visualiser is a standalone React component for the architecture view. The practical consequence of that split is that the catalog is not a hosted service you point at a database. It is an application you run, and the content it renders comes from resource files in the project. The README describes versioning as full semantic versioning for events, commands, services and more, which only makes sense if those things exist as addressable files with version fields. The documentation also mentions 15+ generators that auto-generate catalog content from AsyncAPI, OpenAPI, Kafka, Confluent, AWS EventBridge and other sources. So the intended data flow is: your existing contract artifacts are the input, a generator converts them into catalog resources, and the Astro application renders those resources as domains, services, messages, schemas and business flows. The visualiser component and the schema explorer are views over the same resource set. One thing the README does not spell out is the exact on-disk format each resource takes. If you need that before adopting, the official docs site is the place to check, not the README.
Getting a catalog running, and what the CLI actually gives you
The README gives a single command for the initial setup: npx @eventcatalog/create-eventcatalog@latest my-catalog. It then states that you open http://localhost:3000 and start documenting. That is the entire quickstart in the repository README, and it is honest about being a starting point rather than a deployment guide. The scaffolding package is versioned independently from the core application, which matters at upgrade time: @eventcatalog/create-eventcatalog@4.3.11 and @eventcatalog/core@4.10.13 were released within seconds of each other in the same release batch, but the linter sits on its own track at @eventcatalog/linter@1.1.19. Treating these as one version number will get you into trouble. The README also points to a Getting Started guide on the docs site for a guided walkthrough, and that is where installation details beyond the scaffold command live. The README does not document configuration keys, environment variables, or the shape of the catalog config file. It lists OAuth2, RBAC, schema governance and breaking change detection under an enterprise-ready heading without showing how any of them are enabled. If authentication or governance is the reason you are evaluating EventCatalog, you will need the docs and possibly a conversation with the maintainers before you can judge fit.
The AI chat and MCP server change what the catalog is for
The most consequential feature in the README is the least conventional for a documentation tool. EventCatalog ships a built-in AI chat and an MCP server, described as letting you and your tools query your catalog in natural language. This reframes the catalog from a site humans read into a retrieval layer that agents call. The MCP server in particular means the catalog becomes a tool endpoint, not just a set of pages. That has an obvious appeal for teams already wiring agents into their engineering workflow, and an obvious cost. A catalog is an inventory of your internal architecture: service names, ownership boundaries, message contracts, schema fields. Exposing it to a model means deciding who can query it and what leaves your infrastructure. The README does not describe the retrieval mechanism, whether embeddings are computed locally, or which model providers are supported. Those are questions to answer from the docs before enabling the feature on anything sensitive. The schema fields explorer compounds this. It lets you filter and find any property on any field across the entire catalog, which is useful precisely because it indexes everything you have documented. Convenience and exposure scale together here.
Where the resource model breaks down
The design assumes your architecture decomposes into domains, services and messages. Teams with a strong event-driven backbone will find that assumption comfortable. Teams that are mid-migration will not. If half your system is still a batch job writing to a shared database, there is no honest resource type for it, and you will either leave it out (making the catalog an incomplete map that people stop trusting) or force it into a service entry that misrepresents how it works. A catalog with a known blind spot is worse than no catalog, because people consult it and get a confident wrong answer. The second failure mode is maintenance debt. Every resource is a file someone has to update when a contract changes. The generators reduce the cost for sources they support, but generated content still needs review, and the README's list of supported sources is not the same as a guarantee that your specific Kafka setup or your internal schema registry is covered. The third issue is the one the README states plainly and then moves past: the licence is listed as NOASSERTION in the repository metadata while the README badge reads MIT plus Commercial. Those are different signals. Anyone adopting this inside a company needs to read the actual LICENSE file rather than the badge.
How EventCatalog differs from a Backstage-style developer portal
The nearest comparison is a developer portal built on Backstage. Backstage is a framework: you assemble a portal from plugins, write your own frontend, and the catalog is one plugin among many, typically fed from a service registry or a metadata file per component. EventCatalog takes the opposite position. It is an opinionated application with a fixed vocabulary (domains, services, messages, schemas, flows) and a rendering layer already built, including the visualiser and the schema explorer. You get a working architecture view on day one instead of a plugin integration project, and in exchange you accept the project's model of what architecture is. Backstage's flexibility means it can represent almost anything, including things that are not really services. EventCatalog's constraint means it represents message-driven architecture well and other shapes poorly. A second difference is the schema surface. Backstage's core catalog is not built around exploring OpenAPI, AsyncAPI, Protobuf, JSON Schema and Avro fields across every service. EventCatalog treats the schema explorer and the field-level search as headline features. If your pain is contract discoverability rather than service ownership, that is the more direct fit.
Maintenance cost, release cadence and licence implications
The release history shows a steady cadence across three packages, with core, the scaffolding CLI and the linter versioned separately. That is a normal shape for a monorepo with independently published packages, but it means upgrades are not a single version bump. Pinning to a core version and testing the scaffold and linter against it is the safer pattern. The linter package is worth noting: a linter implies rules about how resources must be shaped, and rules imply that a core upgrade can invalidate resources that passed before. Budget for that. On licensing, the repository metadata reports NOASSERTION while the README badge states MIT plus Commercial. A split licence of that kind usually means the open source edition carries one set of terms and an enterprise edition with features like OAuth2, RBAC and schema governance carries another. I cannot confirm from the supplied material which features fall on which side of that line, and this is not legal advice. Read the LICENSE file at the repository root and, if you are deploying commercially, get someone qualified to read it too. The README's own enterprise-ready list is the best hint about what is likely gated, but it is a hint and not a statement of terms.
Editorial conclusion
Adopt EventCatalog if your architecture is already expressed as domains, services and messages and you are willing to keep those resource files in version control alongside the code they describe. Do not adopt it if you want a zero-maintenance wiki, if your system is a single deployable with no meaningful message contracts, or if you cannot accept the MIT plus commercial licence split. Before committing, verify three things: the exact terms in the LICENSE file for the edition you intend to run, whether the generators for your specific source (Kafka, Confluent, AWS EventBridge, AsyncAPI, OpenAPI) produce output you would actually keep, and how the AI chat and MCP server are configured in your deployment, since those features query your catalog contents.
Community notes