Architectural Decision Records (ADRs)

What is an ADR?

An ADR documents why a significant technical decision was made, not just what was decided.

When to Create an ADR

Create an ADR for:

• Technology selection (Next.js vs Remix, Zustand vs Redux)
• Architectural patterns (Server Components default, API design approach)
• Data modeling decisions (SQL vs NoSQL, schema design)
• Security patterns (authentication approach, authorization model)
• Performance trade-offs (caching strategy, bundling approach)

Don't create ADRs for:

• Routine code changes
• Bug fixes
• Refactoring without architectural impact