Skip to main content

Document events at the domain level

· 4 min read
David Boyne
David Boyne
Founder of EventCatalog

I'm excited to share that domains in EventCatalog 3.7.0 can now directly specify which messages they send and receive. This gives your team more flexibility in how you document your architecture.

Domain-level messages

If you practice Domain-Driven Design or think about messaging at the domain level, this update makes EventCatalog work the way you think.

The problem​

Until now, messages in EventCatalog had to be tied to services. Services send events, commands and queries. Services receive them. This works well for many teams.

But some architectures think about messaging differently. You might define "domain events" or "integration events" that represent what a domain publishes, independent of which specific service implements it. The service is just the implementation detail.

There was no clean way to model this in EventCatalog.

What's new​

Domains can now use sends and receives properties in their frontmatter. Document which messages your domain publishes and consumes, just like you do with services.

---
id: E-Commerce
name: E-Commerce Domain
version: 1.0.0
sends:
  - id: OrderCreated
    version: 1.0.0
  - id: PaymentComplete
receives:
  - id: PaymentInitiated
  - id: FraudDetected
    version: 0.0.1
---

Domain messages appear in the sidebar on the domain page under "Publishes Messages" and "Consumes Messages". They link to the message documentation just like service-level messages do.

When you'd use it​

Use domain-level messages when you think about events at a higher level of abstraction. Common scenarios:

  • Domain-Driven Design: You define domain events as part of your ubiquitous language. Services are the implementation.
  • Integration events: You document what domains publish to other domains, regardless of which service actually sends it.
  • Architecture planning: You're designing domain boundaries before implementing services.

You can mix approaches. Some domains use sends and receives. Some domains only have services that send and receive. Both work. Use what makes sense for your architecture.

Events can live anywhere in your catalog, at the domain level or within the service folder. You just need to reference them in your domain frontmatter.

Example of a message living at the domain level

Here we have the OrderCreated event living at the domain level. The event can still be referenced by any service or domain that needs it.

domains/
  Orders/
    events/
      OrderCreated/
        index.mdx

Example of a message living at the service level

Here we have the OrderCreated event living at the service level. The event can still be referenced by any domain that needs it.

services/
  Orders/
    events/
      OrderCreated/
        index.mdx

How it works​

Add sends and receives to any domain's frontmatter:

---
id: Payment
name: Payment Domain
version: 1.0.0
sends:
  - id: PaymentComplete
  - id: PaymentFailed
    version: 2.0.0
receives:
  - id: PaymentInitiated
---

Messages appear in the domain's sidebar under "Publishes Messages" and "Consumes Messages" sections.

Versions are optional. If you omit the version, EventCatalog uses the latest version of that message. Specify a version when you need to reference a specific one.

Domain messages work with all message types: events, commands, and queries.

SDK support​

The EventCatalog SDK supports domain-level messages. Use addEventToDomain(), addCommandToDomain() or addQueryToDomain() to programmatically add messages when generating your catalog:

import { addEventToDomain } from '@eventcatalog/sdk';

await addEventToDomain(
  'E-Commerce',
  { id: 'OrderCreated', version: '1.0.0' },
  { type: 'sends' }
);

This is useful when you're generating your catalog from external sources like schemas, AsyncAPI specs, or code analysis tools.

Getting started​

Upgrade to EventCatalog 3.7.0:

npm install @eventcatalog/core@latest

Add sends and receives to any domain's frontmatter. That's it. The sidebar updates automatically.

Visualizer support is coming soon. Domain-level messages will appear in architecture visualizations in a future release.

Summary​

Domain-level messaging provides another way to model your architecture in EventCatalog. Use it when you think about events at the domain level, or stick with service-level messages if that fits your model better.

Both approaches work. Both can coexist in the same catalog. Use what makes sense for your team.

Learn more:

Get help: