# Architecture Decision Record (ADR) Template

## Overview

Architecture Decision Records document significant architectural decisions along with their context and consequences.

## ADR Format

### Standard Template

```markdown
# ADR-XXXX: [Short Title]

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

## Date
YYYY-MM-DD

## Context
What is the issue that we're seeing that is motivating this decision or change?

## Decision
What is the change that we're proposing and/or doing?

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

### Neutral
- Side effect 1

## Alternatives Considered

### Option 1: [Name]
- Pros: ...
- Cons: ...
- Why rejected: ...

### Option 2: [Name]
- Pros: ...
- Cons: ...
- Why rejected: ...

## References
- [Link to related documentation]
- [Link to discussion thread]
```

## Example ADRs

### ADR-0001: Use Nx Monorepo

```markdown
# ADR-0001: Use Nx Monorepo for Project Organization

## Status
Accepted

## Date
2024-01-15

## Context
The ISA Frontend consists of multiple applications and shared libraries. We need a way to:
- Share code between applications
- Maintain consistent tooling and dependencies
- Enable efficient CI/CD with affected-based testing
- Enforce architectural boundaries

## Decision
We will use Nx as our monorepo tool with the following structure:
- `apps/` - Deployable applications
- `libs/` - Shared libraries organized by domain and type

## Consequences

### Positive
- Single version of dependencies across all projects
- Affected-based testing reduces CI time
- Consistent tooling (ESLint, Prettier, TypeScript)
- Built-in dependency graph visualization

### Negative
- Learning curve for team members new to Nx
- More complex initial setup
- All code in single repository increases clone time

### Neutral
- Requires discipline in library boundaries
- Need to maintain `project.json` and tags

## Alternatives Considered

### Polyrepo
- Pros: Simpler individual repos, independent deployments
- Cons: Dependency management nightmare, code duplication
- Why rejected: Too much overhead for code sharing
```

### ADR-0002: Adopt NgRx Signal Store

```markdown
# ADR-0002: Adopt NgRx Signal Store for State Management

## Status
Accepted

## Date
2024-03-01

## Context
We need a state management solution that:
- Integrates well with Angular signals
- Provides predictable state updates
- Supports devtools for debugging
- Has good TypeScript support

## Decision
We will use NgRx Signal Store for new features and gradually migrate existing stores.

## Consequences

### Positive
- Native signal integration
- Simpler boilerplate than classic NgRx
- Better performance with fine-grained reactivity
- Excellent TypeScript inference

### Negative
- Migration effort for existing NgRx stores
- Different patterns from classic NgRx

### Neutral
- Team needs to learn new API

## Alternatives Considered

### Classic NgRx (Store + Effects)
- Pros: Mature, well-documented
- Cons: Verbose boilerplate, doesn't leverage signals
- Why rejected: Signal Store is the future direction

### Akita
- Pros: Less boilerplate
- Cons: Not Angular-native, less community support
- Why rejected: NgRx has better Angular integration
```

## ADR Naming Convention

```
docs/adr/
├── 0000-adr-template.md          # Template file
├── 0001-use-nx-monorepo.md
├── 0002-adopt-ngrx-signal-store.md
├── 0003-standalone-components.md
└── README.md                      # Index of all ADRs
```

## ADR Index Template

```markdown
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for the ISA Frontend.

## Index

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nx-monorepo.md) | Use Nx Monorepo | Accepted | 2024-01-15 |
| [0002](0002-adopt-ngrx-signal-store.md) | Adopt NgRx Signal Store | Accepted | 2024-03-01 |
| [0003](0003-standalone-components.md) | Migrate to Standalone Components | Accepted | 2024-04-01 |

## Process

1. Copy `0000-adr-template.md` to `XXXX-short-title.md`
2. Fill in the template
3. Submit PR for review
4. Update status once decided
5. Update this index
```

## Best Practices

1. **One decision per ADR** - Keep ADRs focused
2. **Number sequentially** - Never reuse numbers
3. **Record context** - Why was this needed?
4. **Document alternatives** - Show what was considered
5. **Keep concise** - 1-2 pages max
6. **Update status** - Mark deprecated decisions
7. **Link related ADRs** - Reference superseding decisions
8. **Review regularly** - Quarterly ADR review meetings

## When to Write an ADR

Write an ADR when:
- Choosing a framework or library
- Defining code organization patterns
- Setting up infrastructure
- Establishing conventions
- Making trade-offs that affect multiple teams

Don't write an ADR for:
- Small implementation details
- Obvious choices with no alternatives
- Temporary solutions
