Fundamentals

If you are new to EventCatalog, it can be useful to understand the fundamentals of EventCatalog.

EventCatalog is a self hosted open source documentation tool that focuses on bringing discoverability to your architecture.
EventCatalog is powered by markdown and follows docs-as-code principles.
Using EventCatalog you can document various resources including domains, services, messages (events, commands, queries), channels, schemas and owners.
All resources in EventCatalog are optional, so you can pick and choose what you want to document.
EventCatalog is flexible for any architecture style, and can be used in a variety of ways.

Your EventCatalog documentation lives in a repository,
We recommend following the docs-as-code mindset, this is a powerful way to keep your documentation up to date and in sync with your code.
Docs-as-code is the philosophy that you should be writing documentation using the same tools and processes you use for code. In practice, this means:
- Documentation is often written in a markup language such as Markdown.
- Documentation is checked into source control often next to the code it is documenting.
- You use the same tools you use to author code such as source control and code review tools.
- There might be CI/CD processes involved in validating and shipping your documentation.
- You use a static site generator to turn your documentation into an HTML site.
- You can use EventCatalog as a stand alone repository or as part of your existing project (monorepo).
Having EventCatalog as part of your project means you can use the same tools and processes you use for code, including code reviews, version control and CI/CD pipelines.
Following these practices allow us to automate checks and validation of your documentation, and deploy your documentation anytime external systems change, giving you full control over your documentation and how it is published.
If you want to learn more about docs-as-code, you can read the docs-as-code guide.

You can host and deploy EventCatalog anywhere you want.
EventCatalog supports many different software development workflows, and you can use EventCatalog in a variety of ways.
EventCatalog documentation can be automated integrating with schema registries, external systems and CI/CD pipelines.
Here are some common patterns and workflows people use with EventCatalog:
- EventCatalog as a single repository: Keeping your documentation separate from your code, and using EventCatalog to document your architecture.
- EventCatalog next to your code: Keep your code and docs in sync, by having EventCatalog next to your code.
- EventCatalog inside a monorepo: Put your documentation inside your monorepo, and use EventCatalog to document your architecture.
- Federate multiple EventCatalog instances: This is a more advanced way to get started with EventCatalog. This lets your teams have their own EventCatalog instance, and use EventCatalog Federation to connect them together, into one single view of your architecture.

You can automate all or parts of your documentation, helping you keep them in sync with external systems (e.g schema registries, spec files).
You can turn your OpenAPI or AsyncAPI specification files into documentation, or connect EventCatalog to your schema registries (e.g Confluent Schema Registry, Registry on GitHub, Amazon EventBridge, etc).
EventCatalog supports a wide range of integrations, schema registries and external systems.
You can write your own custom integrations using the EventCatalog SDK.

Keeping your documentation up to date is part of your defined workflow, EventCatalog does not enforce any specific workflow.
This means EventCatalog can fit into your existing workflows, or you can create new governance workflows for your organization.

Now you have a good understanding of the fundamentals of EventCatalog, let's get you started with EventCatalog.