Skip to main content

Project structure

View as Markdown

An EventCatalog project is a folder of Markdown files that describe and model your architecture.

You can edit these files directly, or use the optional EventCatalog Editor to create, preview, review, and commit catalog content through a visual workflow.

Each resource type in your catalog (e.g domain, system, message) is represented by a file or folder in your project. EventCatalog reads those files and turns them into a catalog.

You can also bring your own documentation into EventCatalog, such as guides, onboarding material, or runbooks. Learn more about bringing your own documentation.

All resource types are optional. You decide what you want to document, and you can add more resource types later as your catalog becomes more useful to your teams.

Directories and files​

Every EventCatalog project has a few core files used to run and configure the catalog.

Architecture resources exist in folders such as domains/, systems/, services/, and events/. All resources in EventCatalog are optional, it's up to you how you want to model and document your architecture.

EventCatalog creates resources from folders that contain an index.mdx file. For example, domains/Orders/index.mdx creates an Orders domain, domains/Orders/systems/order-management-system/index.mdx creates an order-management-system system inside that domain, and domains/Orders/systems/order-management-system/services/OrderService/index.mdx creates an OrderService service inside that system.

  • eventcatalog.config.js - Configures your catalog.
  • package.json - Defines scripts and dependencies.
  • public/ - Stores static assets that should be served directly.
  • domains/ - Documents business domains and bounded contexts.
  • systems/ - Documents groups of resources that work together to provide a capability.
  • services/ - Documents services, APIs, applications, external systems, jobs, and workers.
  • events/, commands/, queries/ - Documents messages.
  • channels/ - Documents topics, queues, streams, webhooks, or other communication paths.
  • diagrams/ - Documents architecture diagrams and flows.
  • teams/ and users/ - Documents ownership metadata.

Example project tree​

A common EventCatalog project directory might look like this:

You do not need every folder on day one. Start with the resources you know about, then add more as your catalog grows.

What should I create first?​

If you want to create your first few resources you can follow our Learning EventCatalog Guide.

Next Steps​

Now you know some of the ways EventCatalog work, you can start to document some of your architecture resources. Here are some links below to help depending on what you want to document.

Using AI to help

AI is great at helping you document and get going with EventCatalog. You can install our EventCatalog Skills to teach your LLM about EventCatalog, and then ask your LLM to help you get going.