Skip to main content

Fundamentals

EventCatalog is a tool that helps you document your architecture. It let's you document architecture primitives (e.g domains, services, messages, channels, schemas, etc), and helps you document them in a way that is easy to understand and use.

EventCatalog is technology agnostic, and can be used with any technology or schema format in your architecture.

EventCatalog is an open source project with an open core model.

EventCatalog is a documentation tool​

EventCatalog is self hosted, this means you own your own data, and host it wherever you want.

  • EventCatalog is powered by markdown and follows docs-as-code principles.
  • Using EventCatalog you can document architecture primitives 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 can be automated using integrations such as OpenAPI, AsyncAPI, GraphQL, Schema Registries, etc.
  • EventCatalog is flexible for any architecture style, and can be used in a variety of ways.
  • EventCatalog will parse your documentation, and turn it into visualizations of your architecture.

EventCatalog is a visualization tool​

When using EventCatalog, you document the relationships between your architecture primitives. When you do this, EventCatalog will visualize your architecture in a way that is easy to understand for everyone in your organization.

  • Visualize domains in your organization
  • Visualize producers and consumers of messages
  • Visualize bounded contexts in your organization
  • Embed visualizations into your documentation pages
  • Export visualizations as images
  • Embed visualizations into 3rd party systems (e.g BackStage)

EventCatalog is a design tool​

Export your architecture primitives into a design tool, helping you capture business workflows and new ideas.

  • Export your architecture primitives into a design tool, helping you capture business workflows and new ideas.
  • Export your architecture primitives into a design tool, helping you capture business workflows and new ideas.

EventCatalog is powered by markdown and follows docs-as-code principles. This lets you write documentation in your favorite IDE and version control system, review changes, merge and deploy them.

  • Your EventCatalog documentation lives in a repository, and is versioned.
  • 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.

Patterns and workflows for EventCatalog​

EventCatalog is designed to be used in a variety of ways, and can be used in a variety of ways.

EventCatalog is designed to fit into your organization, CI/CD pipelines and workflows.

  • 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.

Automating your documentation​

Keeping your documentation up to date​

  • 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.

Read to build?​

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