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

0001. Record architecture decisions

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

Context

The engine makes quite a few architectural choices that are hard to reverse and practically impossible to deduce just by reading the code. This includes our crate boundaries, our strict determinism stance for worldgen, the server-authoritative simulation model, the content-ID namespacing scheme, and similar foundational concepts.

The reasoning behind these choices is incredibly valuable to future contributors, but it doesn't belong inline in the source code. If we put it there, it would either get lost in the noise or bloat a single guidance file until it became unreadable.

We need a durable, low-ceremony place to record exactly why significant choices were made. This needs to be kept entirely separate from the cross-cutting rules in DEVELOPMENT.md (which simply records what to follow) and from subsystem implementation docs (which record how a system works).

Decision

We will use Architecture Decision Records (ADRs) to capture all significant, hard-to-reverse decisions. We are adopting the lightweight format popularized by Michael Nygard.

• Each ADR lives as a single Markdown file inside docs/adr/, numbered sequentially (e.g., 0001-..., 0002-...).
• Each record must carry a clear status (Proposed, Accepted, Deprecated, or Superseded by ...) and a date.
• Records are strictly append-only. Once we accept an ADR, we do not edit it to reflect a later change of mind. Instead, we write a brand new ADR and mark the old one as Superseded.
• We start all new records by copying template.md.

Consequences

• The actual rationale behind significant choices is permanently preserved with its historical context, completely independent of how the codebase evolves later.
• DEVELOPMENT.md stays lean. It can simply state a rule and link to the relevant ADR to explain it, rather than carrying a massive justification inline.
• This requires a small but ongoing discipline from the team: if you make a significant architectural choice, you are expected to write an ADR for it. (Trivial or easily reversible choices don't need one).
• Because the records are numbered and append-only, the directory just grows monotonically over time without any single file turning into a bottleneck.