Architectural Decision Records (ADR) Templates

# ADR-{number}: {Title}

**Status:** {Proposed | Accepted | Deprecated | Superseded}
**Date:** {YYYY-MM-DD}
**Deciders:** {List of people involved}
**Technical Story:** {Link to issue/ticket}

## Context

What is the issue we're facing in a given context?
- What are the current constraints?
- What are the requirements?
- What forces are at play (technical, business, political)?

## Decision

What is the change we're proposing/making?
- Be specific and concrete
- Use active voice: "We will..."

## Consequences

What becomes easier or more difficult to do because of this change?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

### Neutral
- Implication 1

## Alternatives Considered

What other options did we evaluate?

### Alternative 1: {Name}
- Description
- Pros
- Cons
- Why rejected

### Alternative 2: {Name}
- Description
- Pros
- Cons
- Why rejected

## Compliance

How will we ensure this decision is followed?
- Code review checks
- Automated tests
- Linting rules
- Documentation updates

## References

- [Link to relevant docs]
- [Link to research]
- [Link to related ADRs]

# ADR-003: Use Zustand for Client State Management

**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Frontend Team
**Technical Story:** #234

## Context

Our React application currently uses Redux Toolkit for state management. As the app grows, we're experiencing:
- Boilerplate overhead (actions, reducers, selectors)
- Difficulty with TypeScript inference
- Complex async logic with thunks
- Large bundle size (~50KB)

We need a simpler, more TypeScript-friendly state management solution that:
- Reduces boilerplate
- Has excellent TypeScript support
- Is lightweight (<5KB)
- Handles async state easily

## Decision

We will adopt Zustand as our primary client state management library.

```typescript
// Simple, typed store
import { create } from 'zustand';

interface TodoStore {
  todos: Todo[];
  addTodo: (text: string) => void;
  removeTodo: (id: string) => void;
}

export const useTodoStore = create<TodoStore>((set) => ({
  todos: [],
  addTodo: (text) =>
    set((state) => ({
      todos: [...state.todos, { id: nanoid(), text, done: false }],
    })),
  removeTodo: (id) =>
    set((state) => ({
      todos: state.todos.filter((todo) => todo.id !== id),
    })),
}));

## Example: TypeScript Configuration ADR

```markdown
# ADR-007: Enable Strict TypeScript Mode

**Status:** Accepted
**Date:** 2024-02-01
**Deciders:** Engineering Team
**Technical Story:** #456

## Context

Our TypeScript configuration currently has:
- `strict: false`
- Mix of implicit `any` types
- Nullable values not handled consistently
- Type errors caught late in CI

This leads to:
- Runtime errors that TypeScript should catch
- Unclear function contracts
- Difficult refactoring

## Decision

We will enable strict mode in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

## Best Practices

1. **Number ADRs sequentially** - Easy to reference
2. **Update status** - Mark when superseded
3. **Document context fully** - Explain constraints and forces
4. **Be specific** - Concrete decisions, not vague statements
5. **List alternatives** - Show due diligence
6. **Include code examples** - Show how decision manifests in code
7. **Define compliance** - Make decision enforceable
8. **Link to references** - Provide supporting material
9. **Keep concise** - 1-2 pages maximum
10. **Commit to repo** - Version control decisions