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 subdomains​

A subdomain is just another domain resource. But your parent domain references the subdomains.

First you need to create your subdomain. You can do this in the /domains folder or in a /subdomains folder.

Examples

  1. /domains/MySubDomain/index.mdx
    • Just like any other domain resource.
  2. /domains/MyParentDomain/subdomains/MySubDomain/index.mdx (added in v2.40.0)
    • You nest the subdomain within the parent domain. (recommended)

Once you have created your subdomain, you can reference it from your parent domain.

Referencing subdomains​

To add a subdomain to a domain you need to reference the subdomain from the domain markdown file.

We do this using the domains property.

In this example we are adding the Orders and Customers subdomains to the Ecommerce domain.

/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 />

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

Tips for subdomain content​

Subdomains are 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.