Skip to main content

Architectural Decision Records (ADRs)

Introduction to ADRs​

Architectural Decision Records (ADRs) are documents that capture important architectural decisions made along with their context and consequences. We use ADRs to document significant decisions that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques of our software projects.

Why Use ADRs?​

ADRs provide several benefits to our engineering team:

  1. Transparency: They make the decision-making process visible and clear to all team members
  2. Knowledge sharing: They help new team members understand why certain technical choices were made
  3. Future reference: They provide context for future changes and modifications
  4. Alignment: They ensure all team members are aligned on architectural decisions
  5. Consistency: They promote consistent approaches across projects

When to Create an ADR​

Create an ADR when making decisions that:

  • Have a significant impact on the software architecture
  • Affect multiple components or teams
  • Introduce new technologies or frameworks
  • Change established patterns or approaches
  • Involve significant trade-offs
  • Would be difficult or expensive to change later

Examples of decisions that warrant an ADR:

  • Selecting a new frontend framework
  • Changing database technology
  • Implementing a microservices architecture
  • Adopting a new authentication strategy
  • Choosing a state management approach
  • Implementing a caching strategy

ADR Template​

Use the following template for creating ADRs:

# ADR-[number]: [Title]

## Date
[YYYY-MM-DD]

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

## Context
[Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?]

## Decision
[Describe the decision that was made. Be clear and concise about what the decision entails.]

## Alternatives Considered
[What other options were considered? Why weren't they chosen?]

## Consequences
[What becomes easier or more difficult because of this change? What are the trade-offs?]

## Implementation
[If applicable, describe how this decision will be implemented]

## Related Documents
[List any related documents, links, or references]

Example ADR​

Here's an example of a completed ADR:

# ADR-001: Using React Server Components for New Projects

## Date
2025-02-15

## Status
Accepted

## Context
As we begin new projects, we need to decide on the frontend architecture approach. NextJS 15 introduces React Server Components (RSC) as a first-class feature, which allows components to render on the server with zero client-side JavaScript by default. This may significantly improve performance and SEO while simplifying our data fetching patterns.

We need to decide whether to adopt RSC as our standard approach for new projects or continue with a client-side rendering approach.

## Decision
We will adopt React Server Components (RSC) with NextJS 15 as our standard approach for all new projects. This means:

1. Using the App Router instead of the Pages Router
2. Making server components the default, with client components used only when necessary
3. Leveraging server-side data fetching directly in components
4. Using NextJS's built-in caching and revalidation mechanisms

## Alternatives Considered

### Traditional Client-Side Rendering (CSR)
- Pros: Team is familiar with this approach, extensive existing patterns
- Cons: Performance concerns, SEO challenges, more client-side JavaScript

### Static Site Generation (SSG)
- Pros: Excellent performance, good for content-heavy sites
- Cons: Not suitable for dynamic content, build times can be long

### Server-Side Rendering (SSR) without RSC
- Pros: Good initial load performance, SEO benefits
- Cons: Higher server load, potential for slower Time To Interactive

## Consequences

### Positive
- Improved performance with reduced client-side JavaScript
- Better SEO as content is server-rendered
- Simplified data fetching directly in components
- Reduced need for client-side state management
- Better security as sensitive operations stay on the server

### Negative
- Learning curve for engineers not familiar with RSC
- Need to carefully manage the boundary between server and client components
- Some third-party libraries may not be compatible with RSC
- Potential for increased complexity in managing server/client code split

## Implementation
1. Create a new NextJS 15 starter template with RSC examples
2. Conduct internal training sessions on RSC best practices
3. Update our coding standards documentation
4. Start using RSC in the next greenfield project
5. Review and adjust our approach after the first project

## Related Documents
- [NextJS App Router Documentation](https://nextjs.org/docs/app)
- [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0188-server-components.md)
- [Internal RFC Discussion](https://github.com/kirana-labs/rfcs/pull/12)

ADR Workflow​

Follow this process for creating and managing ADRs:

  1. Identify the need for an architectural decision
  2. Research and discuss options with relevant stakeholders
  3. Draft the ADR using the template provided
  4. Share for feedback with the engineering team
  5. Revise based on feedback
  6. Finalize and publish the ADR in the project's documentation
  7. Implement the decision
  8. Update the status as needed (from "Proposed" to "Accepted", etc.)

Where to Store ADRs​

Store ADRs in a dedicated docs/architecture/decisions directory in each project repository. Name the files using the format adr-[number]-[kebab-case-title].md.

For organization-wide architectural decisions, store them in our central documentation repository (this one).

ADR Numbering​

ADRs are numbered sequentially, starting from 001. The numbering is specific to each project, so every project will have its own ADR-001.

For organization-wide ADRs, use a prefix: ORG-ADR-001.

Updating ADRs​

ADRs are immutable once accepted. If a decision needs to be changed:

  1. Create a new ADR that references the old one
  2. Update the status of the old ADR to "Superseded by ADR-X"
  3. Document the reasons for the change in the new ADR

Best Practices for Writing ADRs​

  1. Be concise: ADRs should be short and to the point
  2. Focus on the rationale: Explain why the decision was made
  3. Document trade-offs: Be transparent about the pros and cons
  4. Use plain language: Avoid jargon and acronyms when possible
  5. Include context: Help future readers understand the environment in which the decision was made
  6. Reference sources: Link to relevant documentation or discussions

ADR Review Process​

  1. The author creates a pull request with the new ADR
  2. At least two senior engineers review the ADR
  3. The tech lead or architect approves the final decision
  4. The ADR is merged and becomes part of the project documentation

Example Decision Areas​

Here are some common areas where ADRs are valuable:

Frontend Architecture​

  • Component library selection
  • State management approaches
  • Styling methodology (CSS-in-JS, CSS Modules, etc.)
  • Client-side vs. server-side rendering strategy

Backend Architecture​

  • API design (REST, GraphQL, etc.)
  • Authentication and authorization mechanisms
  • Error handling strategies
  • Logging and monitoring approaches

Data Architecture​

  • Database technology selection
  • Schema design principles
  • Caching strategies
  • Data access patterns

DevOps & Infrastructure​

  • Deployment strategies
  • CI/CD pipeline design
  • Infrastructure as Code approaches
  • Monitoring and observability solutions

Conclusion​

Architectural Decision Records are a valuable tool for documenting important technical decisions. By following this process, we create a shared understanding of our architecture and its evolution over time.

Begin using ADRs for your next significant technical decision, and help build our organizational knowledge base.