# Creating ADRs

Copy as Markdown[View as Markdown](/docs/development/guides/adrs/creating-adrs.md)

***

**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[​](#write-your-first-adr "Direct link to 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[​](#add-optional-fields "Direct link to 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[​](#recommended-body-structure "Direct link to 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[​](#next-steps "Direct link to Next steps")

* [Link decisions to resources](/docs/development/guides/adrs/linking-resources.md)
* [Model relationships between decisions](/docs/development/guides/adrs/relationships.md)
* [ADR frontmatter API reference](/docs/api/adr-api.md)