# Create an ADR

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

***

[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice and can be rendered and assigned to resources in EventCatalog.

![Architecture decision record page in EventCatalog](/assets/images/adr-overview-ebec9efb6746c4757fb77262a3c4d326.png)

## Creating an ADR[​](#creating-an-adr "Direct link to Creating an ADR")

### Automatic Creation[​](#automatic-creation "Direct link to Automatic Creation")

Copy this prompt and paste it into your coding agent. Your agent can help you choose where the ADR should live, create the right folder structure, and write the first draft of the decision record.

### Manual Creation[​](#manual-creation "Direct link to Manual Creation")

ADRs live in an `adrs` folder. EventCatalog discovers any `index.mdx` file inside an `adrs` directory, regardless of where that directory lives in your catalog.

You can place ADRs:

At the root of your catalog:

* adrs
  <!-- -->
  /
  * choose-kafka
    <!-- -->
    /
    * index.mdx

Inside a domain:

* domains
  <!-- -->
  /
  * Orders
    <!-- -->
    /
    * adrs
      <!-- -->
      /
      * event-driven-orders
        <!-- -->
        /
        * index.mdx

ADRs can also live inside a system folder when the decision is specific to that system.

## Create the ADR file[​](#create-the-adr-file "Direct link to Create the ADR file")

Create an `index.mdx` file for the ADR.

Here is a minimal ADR with all required fields.

adrs/choose-kafka/index.mdx

```
---
# Unique identifier for the ADR. Used for URLs and references.
id: choose-kafka

# Display name rendered in EventCatalog.
name: Choose Kafka for domain event distribution

# Version of the ADR.
version: 1.0.0

# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
status: accepted

# Date the decision was made or proposed.
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

```
---
# Unique identifier for the ADR. Used for URLs and references.
id: choose-kafka

# Display name rendered in EventCatalog.
name: Choose Kafka for domain event distribution

# Short summary shown in lists and page headers.
summary: Kafka is the primary backbone for inter-domain event distribution.

# Version of the ADR.
version: 1.0.0

# Current lifecycle status: proposed, accepted, rejected, deprecated, or superseded.
status: accepted

# Date the decision was made or proposed.
date: 2026-05-26

# Optional owners. References team or user ids.
owners:
  - platform-team

# Optional decision makers. References team or user ids.
decisionMakers:
  - architecture-board

# Optional resources affected by this decision.
appliesTo:
  - type: domain
    id: Orders
  - type: service
    id: PaymentService
  - type: event
    id: PaymentAccepted

# Optional badges rendered on the ADR page.
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/resources/adrs/linking-resources.md)
* [Model relationships between decisions](/docs/development/guides/resources/adrs/relationships.md)
* [Architecture decision records reference](/docs/development/guides/resources/adrs/reference.md)