Fundamentals
EventCatalog is a self-hosted tool to document, visualize and collaborate on your software architecture. You document it using software primitives and patterns such as domains, systems and resources, rather than scattered documentation pages (e.g. Confluence).
EventCatalog follows the docs-as-code pattern. Your documentation is stored in code using markdown (MDX) and stays private, in your own repository and infrastructure.
At its core, EventCatalog gives you a small set of building blocks for your documentation.
- Domains - a domain describes a business boundary.
- Systems - a system is a collection of resources that work together to perform a function.
- Resources - individual resources (e.g. services, messages, data stores) that can be assigned to systems or domains.
All building blocks are optional in your catalog. It's up to you how you want to model your documentation.
Want to match your c4 model?, you can. Want to document a monolith you can. Want to document distributed systems you can. We focus on architecture primitives and let you fill in the details.
The EventCatalog model
Domains describe a business capability or boundary. They help users understand the boundaries in your architecture, such as Shopping, Payments, Fulfilment, or Customer.
Systems give your catalog an operating shape. A system is a collection of resources that work together to perform a function. For example, a Shopping domain might contain a Cart System and a Promotion System.
Resources are the documented building blocks inside your architecture. They can include:
- Services, such as APIs, workers, frontends, and backends.
- Messages, such as events, commands, and queries.
- Data stores, such as databases, caches, and file stores.
- Entities, such as
Order,Customer, orPayment. - Data products, such as warehouse tables or analytical datasets.
- Agents, such as customer support AI agents.
- Flows, such as business workflows.
Contracts are attached to resources. Schemas, OpenAPI specs, AsyncAPI specs, and GraphQL schemas help users understand the data and interfaces that resources produce, consume, or implement.
Teams and users can own domains, systems, resources, and contracts. This makes ownership part of the architecture model, not a separate spreadsheet.
Levels of detail
Architecture documentation has different audiences, and EventCatalog can be useful to anyone in your organization. Stakeholders want the big picture, and developers want the implementation details.
Every diagram in EventCatalog has three levels of detail, L1, L2 and L3, and they mean the same thing on every diagram:
| Level | What you see | What it answers | Example |
|---|---|---|---|
| L1 | Domains, systems and the relationships between them | Which business boundaries and systems exist, and how do they depend on each other? | Shopping domain, Cart System |
| L2 | The services and data stores inside them, and how they connect | What runs inside a system, and what does it talk to? | Cart API, cart database |
| L3 | Everything in L2, plus the messages and channels | What flows between services? | CartUpdated event, cart.events topic |
When a level doesn't apply to a diagram, it's greyed out. On a service diagram, for example, L1 is greyed out because there are no domains or systems to show above it. Read more in the domain diagram and system diagram docs.
Contracts and ownership sit across these levels. A service can implement an OpenAPI contract. A message can have a schema. A team can own a domain, system, or resource.
This gives different users a way into the same catalog. Architects can start at L1, platform teams can explore the services and data stores in L2, and developers can drill into the messages and contracts they work with every day in L3.
Docs-as-code
EventCatalog is a docs-as-code tool. This means you can store your documentation in your existing Git repository, version it, and use your existing workflows to review and merge changes.
This also let's you define custom workflows and patterns in your organization for documentation and automation.
It's up to you where you define your catalog (or catalogs). Here are some examples:
| Pattern | Description |
|---|---|
| Standalone repo | Keep documentation separate from code |
| Next to your code | Docs live alongside the services they describe |
| Monorepo | Documentation as part of your existing monorepo |
| Federated | Multiple EventCatalog instances connected into one view |
Living documentation
Your documentation can also be automated, keeping your implementation details close to your documentation. There are many integrations or you can create your own automations with our SDK. We also have started building some AI Agents to help you manage your documentation in CI/CD environments.
Visual editing
You can also use EventCatalog Editor to maintain your catalog through a local visual workflow.
The editor runs on top of your EventCatalog project, writes changes back to the same local files, and gives you a Git-backed way to review and publish changes. This helps developers, architects, analysts, and product owners contribute to the catalog without needing to work directly in Markdown files.
Ready to build?
Now that you understand the fundamentals, get started with EventCatalog.