# `docs/decisions/`

Architecture Decision Records (ADRs). MADR-format. One file per decision, numbered sequentially.

| #                                                 | Title                                                     | Status   |
| ------------------------------------------------- | --------------------------------------------------------- | -------- |
| `0000`                                            | Template (don't accept this one)                          | Template |
| [`0001`](0001-use-turborepo-pnpm.md)              | Use Turborepo + pnpm for the monorepo                     | Accepted |
| [`0002`](0002-use-prisma-and-ef-core-parallel.md) | Use Prisma AND EF Core against the same Postgres          | Accepted |
| [`0003`](0003-use-angular-signals.md)             | Use Angular Signals + Standalone (no NgRx)                | Accepted |
| [`0004`](0004-use-clean-architecture-dotnet.md)   | Use Clean Architecture for the .NET API                   | Accepted |
| [`0005`](0005-jwt-plus-refresh-token-strategy.md) | JWT access + rotating refresh token (hashed in DB)        | Accepted |
| [`0006`](0006-design-tokens-as-single-source.md)  | Design tokens are the single source of truth              | Accepted |
| [`0007`](0007-multi-tenant-strategy.md)           | Multi-tenant strategy — row-level scoping                 | Accepted |
| [`0008`](0008-observability-otel-baseline.md)     | OpenTelemetry as the observability baseline               | Accepted |
| [`0009`](0009-pdpa-compliance-baseline.md)        | PDPA + GDPR baseline — audit + anonymize + classification | Accepted |
| [`0010`](0010-mcp-security-baseline.md)           | MCP security baseline                                     | Accepted |

## How to add an ADR

1. `cp 0000-template.md NNNN-<kebab-title>.md` (highest existing number + 1).
2. Fill every section. N/A is fine — write "N/A" explicitly.
3. PR with reviewers from the relevant teams.
4. Status flips to **Accepted** on merge.
5. Update this index.

## When to write an ADR

Write one when:

- A decision is **load-bearing** — undoing it later would be costly.
- A decision is **non-obvious** — a future reader would otherwise ask "why?".
- An existing ADR is being changed — supersede it explicitly.

Don't write one for:

- Style choices already in `CLAUDE.md`.
- Pure mechanics (lockfile bumps, refactors that preserve behavior).
- Naming things.

## Supersession

When ADR-B supersedes ADR-A:

- Edit ADR-A: change Status to `Superseded by NNNN-<title>`.
- ADR-B references ADR-A in its "Related" section.
- Never delete an ADR — the supersession trail is the value.
