Architecture Decision Records
Document Every Architecture Decision with Context

Architecture Decision Records in Archyl are linked directly to C4 model elements, providing traceable context for every decision. Know not just what your system looks like, but why it was designed that way.

View pricing
app.archyl.com

Aurora Commerce

Platform team

Project

Systems

Storefront
Checkout
Payments
Fulfilment
AL

Ada Lovelace

Architect

Aurora Commerce/Decisions/ADR-017
Search the architecture…K
New ADR
ALMDKS
AI

Decision records

23
AllAcceptedProposedSuperseded
017

Enforce rate limiting at the API gateway

ProposedOct 143
016

Idempotency keys on payment operations

ProposedOct 92
015

Split payments out of Checkout

AcceptedSep 304
014

PostgreSQL as the single source of truth

AcceptedSep 125
013

Event bus for order side effects

AcceptedAug 283
012

Synchronous fraud check on checkout

SupersededAug 22
011

Per-team ownership of containers

AcceptedJul 196
ADR-017·Updated Oct 14 by Ada Lovelace

Enforce rate limiting at the API gateway

ProposedDeciders
ALMDKS
Oct 14, 2026

Context

Checkout API and Payments API each throttle requests in-process, with different limits. Bursts during the October sale exhausted the Payments pool while the gateway stayed idle.

Decision

All throttling moves to the API Gateway. Services stop implementing their own limiters; limits are declared per route in gateway/limits.yaml.

Consequences

One place to tune limits and observe rejections. The gateway becomes a hard dependency of every public route, so it runs with three replicas minimum.

Linked elements

API GatewayContainer
Checkout APIAPI
RateLimiterComponent

Discussion

MD

Marc Dubois 2h

Agreed. @Kenji Sato can we set the default to 600 req/min per client?

👍 4🚀 2👀 1
The problem

Pain you know too well

These challenges compound over time. The longer they go unaddressed, the more they cost in engineering time and reliability.

Decisions are lost in Slack and meetings

Critical architecture decisions are made in Slack threads, Zoom calls, and whiteboard sessions. Months later, nobody remembers why the system works this way.

No link between decisions and architecture

Even when ADRs exist in wikis, they are disconnected from the architecture diagrams. You cannot see which elements are affected by which decisions.

Past decisions get relitigated

Without accessible records, new team members question or redo past decisions, wasting engineering time and creating confusion.

How it works

Up and running in a few steps

1

Create an ADR in Archyl

Document the decision, context, options considered, and the chosen approach using the structured ADR editor.

2

Link to C4 elements

Connect the ADR to the specific systems, containers, or components it affects. The decision becomes part of the element's context.

3

Browse decisions on any element

Click any C4 element to see all linked ADRs. Understand why it exists, why it was designed this way, and what alternatives were considered.

4

Query ADRs with AI assistants

Use the MCP server to ask AI assistants about past decisions: 'Why did we choose PostgreSQL?' 'What alternatives were considered for the auth service?'

Capabilities

Everything this feature does for you

ADRs Linked to C4 Elements

Every ADR is connected to the architecture elements it affects. Navigate from diagram to decision seamlessly.

Decision Lifecycle Tracking

Track ADR status: proposed, accepted, deprecated, superseded. See the evolution of decisions over time.

Searchable Decision History

Find past decisions by keyword, element, date, or status. Never lose track of why something was built a certain way.

AI-Queryable Decisions

MCP server tools let AI assistants query ADRs. New team members get instant answers about architectural rationale.

Use cases

Where teams use it

01

Technology Selection Decisions

Document why you chose specific databases, frameworks, or cloud services. Link the ADR to the containers that use them.

02

Security Architecture Choices

Record security-critical decisions and link them to trust boundaries and data-handling components.

03

Migration & Deprecation Plans

Document migration decisions and link them to the systems being migrated or deprecated.

Keep exploring

Explore all features

API Contracts

Attach API Contracts to Your Architecture Model

Learn more

Ownership Map

Know Who Owns Every Part of Your Architecture

Learn more

Technology Radar

Track Technology Adoption Across Your Organization

Learn more
Free plan forever

Give every architecture decision a permanent home

Structured ADRs linked to C4 elements. Never lose the context behind your architecture decisions.

  • No credit card
  • Set up in five minutes
  • Viewers are always free
Book a demoRead the quickstart

Architecture Decision Records (ADR) Tool

Link architecture decisions directly to C4 elements. Track the why behind every architecture choice with structured ADRs.

Architecture Decision Records

Document Every Architecture Decision with Context

Architecture Decision Records in Archyl are linked directly to C4 model elements, providing traceable context for every decision. Know not just what your system looks like, but why it was designed that way.

Architecture Decision Records (ADR) | Archyl

Link ADRs to C4 model elements for traceable architecture decisions. Document the why behind your system design with structured, searchable records.

architecture decision records, ADR tool, architecture decisions documentation, ADR linked to C4, traceable architecture decisions

Decisions are lost in Slack and meetings

Critical architecture decisions are made in Slack threads, Zoom calls, and whiteboard sessions. Months later, nobody remembers why the system works this way.

No link between decisions and architecture

Even when ADRs exist in wikis, they are disconnected from the architecture diagrams. You cannot see which elements are affected by which decisions.

Past decisions get relitigated

Without accessible records, new team members question or redo past decisions, wasting engineering time and creating confusion.

Create an ADR in Archyl

Document the decision, context, options considered, and the chosen approach using the structured ADR editor.

Connect the ADR to the specific systems, containers, or components it affects. The decision becomes part of the element's context.

Browse decisions on any element

Click any C4 element to see all linked ADRs. Understand why it exists, why it was designed this way, and what alternatives were considered.

Query ADRs with AI assistants

Use the MCP server to ask AI assistants about past decisions: 'Why did we choose PostgreSQL?' 'What alternatives were considered for the auth service?'

ADRs Linked to C4 Elements

Every ADR is connected to the architecture elements it affects. Navigate from diagram to decision seamlessly.

Decision Lifecycle Tracking

Track ADR status: proposed, accepted, deprecated, superseded. See the evolution of decisions over time.

Searchable Decision History

Find past decisions by keyword, element, date, or status. Never lose track of why something was built a certain way.

AI-Queryable Decisions

MCP server tools let AI assistants query ADRs. New team members get instant answers about architectural rationale.

Technology Selection Decisions

Document why you chose specific databases, frameworks, or cloud services. Link the ADR to the containers that use them.

Security Architecture Choices

Record security-critical decisions and link them to trust boundaries and data-handling components.

Migration & Deprecation Plans

Document migration decisions and link them to the systems being migrated or deprecated.

Give every architecture decision a permanent home

Structured ADRs linked to C4 elements. Never lose the context behind your architecture decisions.