Skip to content

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 with Supersedes: 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.md so 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