Skip to content

Architecture Decision Records

ADRs capture non-obvious decisions and their rationale so future contributors (human or agent) understand why the project looks the way it does, not just what it looks like.

Conventions

  • File name: NNNN-kebab-case-title.md, four-digit zero-padded sequence.
  • Each ADR has: Status, Date, Context, Decision, Consequences, and (when useful) Triggers for revisiting.
  • Status values: Proposed, Accepted, Superseded by NNNN, Deprecated.
  • Editing an Accepted ADR depends on age.
  • Less than one week old (still fresh in everyone's mind): just edit the text directly. Update the Date field to the most recent edit. No amendments section, no superseding ADR.
  • Older than one week: the original decision text and rationale stay put. For substantive reversals or replacements, write a new ADR that supersedes the old one. For tightly-scoped clarifications or implementation tweaks, append a dated ## Amendments section at the bottom of the original ADR.

Index

  • 0001 — Data access strategy — EF Core as default, Dapper as escape hatch for hot paths, Npgsql binary COPY for bulk import/export.
  • 0002 — Sign-in token strategy — JWT access (≤6h, default 30min) + rotating opaque refresh token in HttpOnly cookie; replay detection via token families.
  • 0003 — API / Frontend separation — Molib.Api is a pure JSON API; user-facing URLs (email links, share links) point at the SPA, which mediates every flow.
  • 0004 — Database collation — C.UTF-8 at the database level (glibc-stable, fast, predictable); ICU collations applied per-column where natural-language ordering matters.
  • 0005 — Test mocking policy — Mock only true external dependencies; everything else (DB, Hangfire, our own services) runs real in tests.