How to Run Architecture Decision Records (ADRs)?

How to run Architecture Decision Records (ADRs)?

Run ADRs by creating a standardized template in NoteVault, documenting decisions when they're made (not after), including context and alternatives considered, linking ADRs to implementation tasks, and reviewing ADRs when technology changes. NoteVault's revision history tracks decision evolution over time.

ADR template

# ADR-001: [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Date
2025-01-27

## Context
[Why is this decision needed? What problem are we solving?
What constraints exist?]

## Decision
[What is the change being proposed? Be specific.]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Tradeoff 1]
- [Tradeoff 2]

## Alternatives Considered

### Option A: [Name]
- Pros: [Advantages]
- Cons: [Disadvantages]
- Why rejected: [Reason]

### Option B: [Name]
- Pros: [Advantages]
- Cons: [Disadvantages]
- Why rejected: [Reason]

## Implementation
- Task: [Link to GitScrum task]
- Timeline: [When to implement]

## References
- [Related documentation]
- [External resources]

ADR labels for tasks

Example ADR

# ADR-003: Use PostgreSQL for Primary Database

## Status
Accepted

## Date
2025-01-27

## Context
We need to choose a primary database for the new application.
Requirements:
- ACID compliance
- JSON support for flexible schemas
- Strong ecosystem and tooling
- Team familiarity

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

## Consequences

### Positive
- Strong ACID compliance
- Excellent JSON/JSONB support
- Team has PostgreSQL experience
- Rich extension ecosystem
- Good cloud support (RDS, Cloud SQL)

### Negative
- Horizontal scaling requires more planning
- Some operations heavier than NoSQL alternatives
- Connection pooling needed at scale

## Alternatives Considered

### MongoDB
- Pros: Easy horizontal scaling, flexible schemas
- Cons: Team unfamiliar, eventual consistency concerns
- Why rejected: Preference for ACID, team experience

### MySQL
- Pros: Team knows it, simple setup
- Cons: Weaker JSON support, fewer extensions
- Why rejected: PostgreSQL better fits requirements

## Implementation
- Task: #456 - Database infrastructure setup
- Timeline: Sprint 5

## References
- PostgreSQL 16 release notes
- Cloud provider comparison document

ADR workflow:

1. Identify decision - Recognize architecture choice
2. Draft ADR - Use template in NoteVault
3. Propose - Share with team for review
4. Discuss - Gather feedback, consider alternatives
5. Decide - Accept, reject, or revise
6. Update status - Mark as accepted
7. Implement - Create and link tasks
8. Reference - Point to ADR in code comments

NoteVault ADR index

# Architecture Decision Records

## Index

| ID | Title | Status | Date |
|----|-------|--------|------|
| ADR-001 | Monorepo structure | Accepted | 2024-12 |
| ADR-002 | React for frontend | Accepted | 2024-12 |
| ADR-003 | PostgreSQL database | Accepted | 2025-01 |
| ADR-004 | REST vs GraphQL | Proposed | 2025-01 |

## By Category

### Infrastructure
- ADR-003: PostgreSQL database
- ADR-005: AWS for hosting

### Frontend
- ADR-002: React for frontend
- ADR-007: Tailwind for styling

### Backend
- ADR-004: REST vs GraphQL
- ADR-008: Node.js runtime

When to create ADRs

Related articles

• Creating effective documentation culture
• How to build a knowledge base for development teams
• How to run effective technical design reviews