Skip to main content

Creating ADRs

View as Markdown
Added in eventcatalog@3.42.0

ADRs are MDX files with a required frontmatter block. Create a new folder inside any adrs directory and add an index.mdx file.

adrs/
  choose-kafka/
    index.mdx       ← your ADR

ADRs can also live inside a domain folder, which keeps domain-specific decisions colocated with the domain.

domains/
  Orders/
    adrs/
      event-driven-orders/
        index.mdx

Write your first ADR​

Here is a minimal ADR with all required fields.

adrs/choose-kafka/index.mdx
---
id: choose-kafka
name: Choose Kafka for domain event distribution
version: 1.0.0
status: accepted
date: 2026-05-26
---

## Context

Services need a reliable backbone for cross-domain event distribution.

## Decision

We will use Apache Kafka as the primary event bus for inter-domain communication.

## Consequences

Teams gain reliable, ordered delivery with replay support. They also take on operational responsibility for the Kafka cluster.

Add optional fields​

Enrich the ADR with owners, decision makers, links to affected resources, and badges.

adrs/choose-kafka/index.mdx
---
id: choose-kafka
name: Choose Kafka for domain event distribution
summary: Kafka is the primary backbone for inter-domain event distribution.
version: 1.0.0
status: accepted
date: 2026-05-26
owners:
  - platform-team
decisionMakers:
  - architecture-board
appliesTo:
  - type: domain
    id: Orders
  - type: service
    id: PaymentService
  - type: event
    id: PaymentAccepted
badges:
  - content: Messaging
    backgroundColor: blue
    textColor: blue
---

## Context

...

## Decision

...

## Consequences

...

Recommended body structure​

EventCatalog does not enforce a particular body format, but the classic ADR structure works well.

Context — the situation or problem that prompted the decision.

Decision — the choice that was made and the reasoning behind it.

Consequences — what happens as a result, both positive and negative.

You can use any markdown content here including headings, tables, code blocks, and MDX components.

Next steps​