adr

Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for this project.

ADRs document architecturally significant decisions: their context, the decision made, and the consequences — both positive and negative. They answer why, not just what.

Index

ADR	Title	Status
001	Interface-based architecture	Accepted
002	UUID as primary key and squadNumber as mutation key	Accepted
003	Use Native ESM instead of CommonJS	Accepted
004	Use Express 5	Accepted
005	Use SQLite with Sequelize ORM	Accepted
006	Integration-first testing strategy	Accepted
007	Node-cache with 1-hour TTL	Accepted
008	Use Pino for structured logging	Accepted
009	Docker and Compose strategy	Accepted
010	Use tsx instead of ts-node	Accepted
011	Football-themed semantic versioning	Accepted

Creating a new ADR

1. Copy template.md to a new file: NNN-short-title.md (zero-padded three-digit number)
2. Fill in all sections following the template guidance
3. Set status to Proposed until agreed upon, then Accepted
4. Add a row to the index table above
5. Reference the ADR number in the relevant PR or issue

Lifecycle

Status	Meaning
Proposed	Draft under discussion
Accepted	Agreed and implemented
Deprecated	No longer recommended but not yet replaced
Superseded	Replaced by a newer ADR (reference provided)

ADRs are append-only: once accepted, update the status field only. To reverse or modify a decision, create a new ADR and mark the old one as Superseded.