Architecture Decision Records (ADRs)¶
This directory captures every architectural decision worth preserving — pinned dependencies, interface choices, cross-cutting conventions, deviations from defaults.
Format¶
Michael Nygard's format — see 0000-template.md. Sourced from joelparkerhenderson/architecture-decision-record, which is the canonical reference for ADR styles, examples, and tooling.
Conventions¶
- Filename:
NNNN-kebab-case-title.md, zero-padded 4-digit ID. - Immutable: once
Status: Accepted, the body is frozen. To change a decision, write a new ADR withSupersedes: ADR-NNNN. - One decision per ADR: if you find yourself writing "and also…", split it.
- Tag the ADR so future readers can grep by area (
db,http,security, …). - Link ADRs from the relevant per-package
AGENTS.mdso the rationale is one click away.
Index¶
| ID | Title | Status | Tags |
|---|---|---|---|
| ADR-0001 | fx over wire for dependency injection | Accepted | core, di |
| ADR-0002 | koanf over viper for configuration | Accepted | core, config |
| ADR-0003 | slog (stdlib) over zap for logging | Accepted | core, observability |
| ADR-0004 | ogen over oapi-codegen for OpenAPI | Accepted | http, api |
| ADR-0005 | river over asynq for background jobs | Accepted | jobs, db |
| ADR-0006 | Pluggable leader election (k8s Lease + pg advisory) | Accepted | leader, runtime |
| ADR-0007 | RFC 9457 Problem Details for HTTP error bodies | Accepted | http, api |
| ADR-0008 | Upload hardening — strip-by-re-encode and SSRF via dialer Control | Accepted | storage, security, ssrf, uploads |
| ADR-0009 | gonertia/v3 for the Inertia.js server adapter | Accepted | http, frontend, inertia |
| ADR-0010 | goenvoy multi-module clients wired onto the framework's resilient HTTP stack | Accepted | integrations, http, metadata, arr |
| ADR-0011 | baruwa-enterprise/clamd for upload malware scanning, fail-closed by default | Accepted | security, storage, supply-chain |
| ADR-0012 | storage/tus dependency choice | Accepted | storage, uploads, tus |
| ADR-0013 | media/audio dependency choice | Accepted | media, audio |
| ADR-0014 | htmltmpl dependency choice | Accepted | http, templating, security |
| ADR-0015 | torrent client abstraction and backend dependencies | Accepted | torrent, media, backends, dependencies |
| ADR-0016 | On-demand image pipeline gated by HMAC signed URLs | Accepted | media, img, http, security |
| ADR-0017 | core/ is a separate, lean Go module |
Accepted | modules, dependencies, governance, breaking-change |
| ADR-0018 | Relicense to EUPL-1.2 + CC-BY-SA-4.0, REUSE, DCO | Accepted | licensing, compliance, governance |
| ADR-0019 | Adopt praetor governance; publish capabilities.yaml |
Accepted | governance, agents, tooling, fleet |
| ADR-0020 | Second-wave praetor conformance and release hardening | Proposed | governance, ci, security, releases, praetor |
| ADR-0021 | Run golusoris CI on GitHub-hosted runners | Superseded by ADR-0022 (runner label) | ci, supply-chain, governance |
| ADR-0022 | Run golusoris CI on ubuntu-26.04 GitHub-hosted runners | Accepted | ci, supply-chain, governance |
| ADR-0023 | Keep hand-written OAuth2 authorization server | Accepted | auth, security, dependencies |
| ADR-0024 | Keep flags provider contract | Accepted | flags, dependencies |
| ADR-0025 | Keep hand-written session engine | Accepted | auth, session, dependencies |
| ADR-0026 | Keep hand-written LLM provider clients | Accepted | ai, llm, dependencies |
| ADR-0027 | Keep the hand-written man page renderer | Accepted | clikit, cli, dependencies |
| ADR-0028 | Outbound HTTP response cache as a transport on bartventer/httpcache and cache/twotier | Accepted | http, cache, security, dependencies |
Numbering policy¶
Use the next available sequential four-digit ID. ADR-0001 through ADR-0007 are backfills: decisions made before the ADR practice was formalised and captured retroactively from commit history. Their status reflects current code, not the original decision date.
ADR-0008 and later follow the normal proposed/accepted lifecycle.
Further reading¶
- joelparkerhenderson/architecture-decision-record — templates + alternatives (MADR, Y-statements, etc.) + tooling (
adr-tools). docs/architecture/— C4 diagrams (PlantUML) referenced from the ADRs.