Skip to main content

Creating subdomains

Added in eventcatalog@2.34.0

Subdomains are optional but can be a great way to group domains together.

Subdomains look and behave the same as domains in EventCatalog, but they introduce a new way to group domains together.

This can be useful if you are following DDD principles, or just want to group domains together.

An example of a domain and subdomain relationship is:

  • Domain: Ecommerce
    • Subdomain: Orders
      • Service: Payment
      • Service: Shipping
    • Subdomain: Customers
      • Service: Profile
      • Service: Address
    • Subdomain: Inventory
      • Service: Products
      • Service: Warehouse

In this example, the Ecommerce domain contains the Orders, Customers and Inventory subdomains. Each subdomain contains services that are related to that subdomain.

When you add a subdomain to a domain, your users will be able to see the relationship between the domain and subdomain, navigate between them and see subdomains within the visualizer.

What do subdomains look like in EventCatalog?​

Example

See subdomain example in the EventCatalog Demo.

Domains Visualizer (with subdomains)​

When you reference a subdomain from a domain, it will appear in the domains visualizer. You can use the legend to highlight resources that are part of a subdomain.

Domains Visualizer (with subdomains)

See subdomain example in the EventCatalog Demo.

Adding a subdomain to a domain​

To add a new subdomain to a domain, you need to reference the subdomain from the (parent) domain markdown file. We do that using the domains property.

We reference the subdomain by its id and optionally provide a version. If no version is provided, the latest version of the subdomain will be used.

Here is an example of the Ecommerce domain with the subdomains added.

/domains/Ecommerce/index.mdx (example)
---
# id of your domain, used for slugs and references in EventCatalog.
id: Ecommerce

# Display name of the domain, rendered in EventCatalog
name: Ecommerce

# Version of the domain
version: 0.0.1

# Short summary of your domain
summary: |
  Domain that contains ecommerce related information

# List of subdomains (version is optional)
domains:
  # Here version is given, the latest version of Orders Domain is used.
  - id: Orders
    version: 0.0.1
  # Here version is not given, the latest version of Customers Domain is used.
  - id: Customers

# Owners of the "parent" domain
owners:
    - dboyne
---

## Overview

Ecommerce domain contains all ecommerce related information for FakeCompany.

<NodeGraph />

That's it!

Once you add your new domain to EventCatalog, it will now show in the docs, visualizer and discoverability table.

warning

You can't nest subdomains in the domains folder (yet). We are working on it!

Adding content​

Just like the domains resource you can write any markdown you want and it will render on your page.

Within your markdown content you can use components to add interactive components to your page.

To find out more read the domain components list.

Tips for subdomain content​

Subdomains are totally optional. But may be useful if you are following DDD principles or just want to group domains together.

If you have any questions or feedback, please reach out on Discord.