synvael/docs/adr/0001-record-architecture-decisions.md

0001. Record architecture decisions

• Status: Accepted
• Date: 2026-06-27

Context

The engine makes a number of architectural choices that are hard to reverse and non-obvious from the code alone: the crate boundaries, the determinism stance for worldgen, the server-authoritative simulation model, the content-ID namespacing scheme, and similar. The reasoning behind such choices is valuable to future contributors but does not belong inline in the source, where it would either be lost or bloat a single guidance file.

A durable, low-ceremony place is required to record why significant choices were made, kept separate from the cross-cutting rules in AGENTS.md (which records what to follow) and from subsystem implementation docs (which record how a system works).

Decision

Architecture Decision Records (ADRs), in the lightweight format popularised by Michael Nygard, are used to capture significant, hard-to-reverse decisions.

• Each ADR is a single Markdown file in docs/adr/, numbered sequentially (0001-..., 0002-...).
• Each record carries a status (Proposed, Accepted, Deprecated, or Superseded by ...) and a date.
• Records are append-only: once accepted, an ADR is not edited to reflect a later change of mind. A new ADR is written instead and the old one is marked Superseded.
• New records are started from template.md.

Consequences

• The rationale behind significant choices is preserved with its historical context, independent of how the code later evolves.
• AGENTS.md stays lean: it can state a rule and link to the ADR that explains it, rather than carrying the justification inline.
• A small, ongoing discipline is required : a contributor making a significant architectural choice is expected to add an ADR for it. Trivial or easily reversible choices do not warrant one.
• Because records are numbered and append-only, the directory grows monotonically without any single file becoming a bottleneck.