# Architecture decisions

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

***

**Added in** `eventcatalog@3.42.0`

[Architecture decision records (ADRs)](https://adr.github.io/) capture why your team made a particular design choice. In EventCatalog, ADRs are first-class resources that live alongside services, events, domains, and flows.

![ADR detail page showing status, decision makers, and linked resources](/assets/images/adr-overview-ebec9efb6746c4757fb77262a3c4d326.png)

[See an example ADR in the demo catalog →](https://demo.eventcatalog.dev/docs/adrs/adr-001-choose-event-driven-orders/1.0.0)

## Why document decisions?[​](#why-document-decisions "Direct link to Why document decisions?")

Architectural choices are often made once and then forgotten. When a new engineer joins or a design is revisited months later, the reasoning behind past decisions is usually lost.

Documenting ADRs in your catalog gives your team:

* **Context** — anyone can see what alternatives were considered and why a particular path was chosen.
* **Traceability** — decisions are linked directly to the services, events, domains, and flows they affect via `appliesTo`.
* **Lifecycle tracking** — each ADR has a status (`proposed`, `accepted`, `rejected`, `deprecated`, `superseded`) so it is clear which decisions are still in force.
* **AI-ready context** — because ADRs sit alongside the resources they govern, the [EventCatalog MCP server](/docs/development/ask-your-architecture/mcp-server/introduction.md) can surface the *why* behind your architecture to AI assistants, not just the *what*. When an LLM is reasoning about a service or event, it picks up the decisions, trade-offs, and constraints recorded in your ADRs.

## Lifecycle statuses[​](#lifecycle-statuses "Direct link to Lifecycle statuses")

Every ADR must declare a `status` field. The available values are:

| Status       | Meaning                                 |
| ------------ | --------------------------------------- |
| `proposed`   | Under discussion, not yet accepted      |
| `accepted`   | In force                                |
| `rejected`   | Considered and deliberately not adopted |
| `deprecated` | Was accepted but is being phased out    |
| `superseded` | Replaced by a newer decision            |

EventCatalog renders a colored badge for each status and shows a warning banner on `deprecated` and `superseded` pages so readers are directed to the current decision.

## Where ADRs live[​](#where-adrs-live "Direct link to Where ADRs live")

ADRs can be placed in any `adrs` folder in your catalog. This lets you keep them at the root level or colocate them with a specific domain.

```
adrs/
  choose-kafka/
    index.mdx
domains/
  Orders/
    adrs/
      event-driven-orders/
        index.mdx
```

## Finding ADRs[​](#finding-adrs "Direct link to Finding ADRs")

ADRs appear on the discover page alongside services, events, domains, and flows. You can search, filter, and browse them the same way you would any other resource.

![Discover page listing decision records with status and badges](/assets/images/discover-adrs-3355b2316d868dc588bb4a4245aa5b62.png)

[Explore decision records in the demo catalog →](https://demo.eventcatalog.dev/discover/adrs)

Linked resources also surface their related ADRs in the sidebar under **Decision Records**, so engineers reading a service or event page can immediately see which architectural decisions affect it.