Architecture Decision Records (ADR)

ADRs capture important architectural decisions made during the development of a project, along with their context and consequences.

What is an ADR?

An Architecture Decision Record is a short document that:

• Records a single architectural decision
• Explains the context and forces at play
• Describes the decision made
• Lists the consequences

When to Write an ADR

Write an ADR when:

• ✅ Choosing between technologies (e.g., database, framework)
• ✅ Making structural decisions (e.g., monolith vs. microservices)
• ✅ Deciding on patterns (e.g., authentication strategy)
• ✅ Making trade-offs that affect the system
• ✅ Any decision others might question later

ADR Structure

A typical ADR includes:

Title

A short, descriptive name for the decision.

Example: "Use PostgreSQL as the Primary Database"

Status

Current state of the decision (handled by ArchDoc's category system):

• In Progress: Decision being drafted
• Accepted: Decision approved and in effect
• Closed: Decision superseded or rejected

Context

Describe the situation and forces at play:

• What problem are we solving?
• What constraints exist?
• What options were considered?

Decision

State the decision clearly:

We will use PostgreSQL as our primary database because...

Consequences

List the positive and negative outcomes:

• What becomes easier?
• What becomes harder?
• What new problems might arise?

Example ADR

# Use PostgreSQL for Primary Database

## Context
We need a database for our SaaS application. We require:
- ACID compliance for financial transactions
- JSON support for flexible document storage
- Strong ecosystem and community support
- Scalability for expected growth

Options considered:
1. PostgreSQL
2. MySQL
3. MongoDB

## Decision
We will use **PostgreSQL** as our primary database.

PostgreSQL provides:
- Full ACID compliance
- Native JSON/JSONB support
- Excellent performance at scale
- Rich extension ecosystem (PostGIS, pg_vector)

## Consequences

### Positive
- Strong data integrity
- Flexibility with JSON columns
- Large talent pool familiar with PostgreSQL
- Good integration with Prisma ORM

### Negative
- Requires more initial setup than SQLite
- Needs proper connection pooling for serverless
- Team needs PostgreSQL-specific training

Best Practices

Keep ADRs Short

• Aim for 1-2 pages maximum
• Focus on the essential information
• Link to external resources for details

One Decision Per ADR

• Each ADR should cover one decision
• Related decisions can reference each other

Write for Future Readers

• Assume the reader has no context
• Explain acronyms and terms
• Include links to relevant resources

Don't Delete, Supersede

• Never delete old ADRs
• Create new ADRs that reference superseded ones
• Mark old ADRs as Closed

Creating an ADR in ArchDoc

1. Navigate to Dashboard > Documents
2. Click New Document
3. Select ADR as the document type
4. Enter a descriptive title
5. Write your content using the editor
6. (Optional) Request sign-offs
7. Save and set category when ready

Related

• Creating Documents
• Sign-off Workflow
• RFC Documents