# Decisions

Each record captures a decision that was expensive to reverse, the alternatives
that were rejected, and the reasoning. They exist so nobody has to re-litigate a
settled question — and so an agent does not "improve" something that was
deliberate.

Read the ones relevant to what you are changing.

| ADR | Decision | Rejected alternatives |
|---|---|---|
| [001](ADR-001-sqlite-with-a-seam.md) | SQLite, with a storage seam for later | PostgreSQL; fixing the write lock in code instead |
| [002](ADR-002-direct-play-only.md) | Direct play only, never transcode | On-demand CPU transcode; remux; pre-transcode |
| [003](ADR-003-mark-missing-never-delete.md) | A vanished file is marked, never deleted | Delete on scan; auto-purge; keep it invisible |
| [004](ADR-004-modular-monolith.md) | One binary with enforced package boundaries | Microservices; unenforced conventions |
| [005](ADR-005-one-item-access-chokepoint.md) | One item-access chokepoint, `internal/catalog` | Leave the duplication; a shared helper; a generic repository |
| [006](ADR-006-table-backed-job-queue.md) | The job queue is a table | Redis or a broker; in-memory goroutines |
| [007](ADR-007-fixed-width-timestamps.md) | Fixed-width timestamps via `core.Stamp` | Integer nanoseconds; six/nine digits; sorting in Go |

## Writing a new one

Add `ADR-00N-short-title.md` with **Status**, **Date**, **Context**, **Decision**,
**Alternatives Considered** (with the reason each was rejected) and
**Consequences**. Do not delete an ADR when a decision changes — write a new one
that supersedes it, so the history stays readable.

Two things make an ADR worth writing: the decision would be expensive to reverse,
and a reasonable person could have chosen differently. If neither is true, a
comment in the code is the right place.