Skip to content

Architecture decisions (ADR)

Significant decisions are recorded here as Architecture Decision Records in the MADR 4 format (ADR 0001). New ADR: copy the template 0000, take the next free number, then run make adr-index. Smaller rulings are in the ruling log DECISIONS.md.

The table below is generated by tools/docs/adr_index.py from the files; make docs fails if it is out of date. Do not edit it by hand.

No. Title Status Date
0000 Template (MADR 4) template 2026-10-11
0001 ADRs in MADR format, DECISIONS.md as the ruling log accepted 2026-10-11
0002 Two repos: public product, private ops repo accepted 2026-10-10
0003 License Apache-2.0 with DCO instead of CLA accepted 2026-10-10
0004 Modular monolith instead of microservices accepted 2026-10-10
0005 Go as the server language accepted 2026-10-10
0006 PostgreSQL from day 1 instead of SQLite accepted 2026-10-10
0007 Typed database access (sqlc) and migration tool accepted 2026-10-10
0008 Hexagonal modules and checked dependency rules accepted 2026-10-10
0009 Commit-ordered event log with a global sequence accepted 2026-10-10
0010 Object storage behind an S3 interface, local driver as the default accepted 2026-10-10
0011 12-factor configuration and secret provider interface accepted 2026-10-10
0012 Multi-arch OCI images, Compose as the installation, OpenTofu per target accepted 2026-10-10
0013 Spec first: OpenAPI 3.1 and AsyncAPI 3.0 are normative, code generation accepted 2026-10-10
0014 API versioning and deprecation policy accepted 2026-10-10
0015 Error format RFC 9457, idempotency, pagination accepted 2026-10-10
0016 Webhooks per Standard Webhooks accepted 2026-10-10
0017 One authorization function, 404 instead of 403, mandatory registration accepted 2026-10-10
0018 Grant model: levels, capabilities, inheritance, no deny accepted 2026-10-10
0019 Identity providers: OIDC, proxy header, local passkey accounts accepted 2026-10-10
0020 Device binding, DPoP, step-up for admin actions accepted 2026-10-10
0021 Hash-chained audit log, separate from telemetry accepted 2026-10-10
0022 Agents and plugins outside the server process accepted 2026-10-10
0023 Signed invocation token and check in the adapter accepted 2026-10-10
0024 Backend policy personal/organization with invariant accepted 2026-10-10
0025 Run as its own object for the live box accepted 2026-10-10
0026 SDKs: generated core plus hand-written layer (Python, TypeScript) accepted 2026-10-10
0027 Flutter for all apps accepted 2026-10-10
0028 Web target only for the admin and statistics console accepted 2026-10-10
0029 Client state, local database and offline queue accepted 2026-10-10
0030 Design tokens as one source with a generator accepted 2026-10-10
0031 Push without content, the app fetches the content itself accepted 2026-10-10
0032 Full-text search in PostgreSQL accepted 2026-10-10
0033 Malware scan of uploads as a separate service accepted 2026-10-10
0034 OpenTelemetry through a collector, local default stack accepted 2026-10-10
0035 SLOs with error budgets and burn-rate alerts accepted 2026-10-10
0036 Releases: SemVer per component, signed artifacts, SBOM, provenance accepted 2026-10-10
0037 App distribution and auto-update channels proposed 2026-10-10
0038 Local gates first: one command identical to CI accepted 2026-10-10
0039 Only GitHub-hosted runners, public from the first push accepted 2026-10-11
0040 SonarQube local and cloud with the same profile and gate accepted 2026-10-10
0041 Dependency updates with Renovate accepted 2026-10-10
0042 Deny-list scanner with the list from the ops repo accepted 2026-10-10
0043 Discord import: read only, dry run, origin key accepted 2026-10-10
0044 Working name and branding as configuration accepted 2026-10-10
0045 Documentation site generator accepted 2026-10-10
0046 Multi-user dev environment only with isolation accepted 2026-10-10
0047 Remove image metadata losslessly accepted 2026-10-10
0048 File download only through the server with short-lived tickets instead of presigned GET accepted 2026-10-10
0049 Machine-readable action catalogue as the single source for docs, lint and code accepted 2026-10-11
0050 Module register as the source for the architecture gate and table ownership accepted 2026-10-10
0051 Worker consumers of the event log with a cursor instead of job inserts in the write path accepted 2026-10-10
0052 One event envelope for gateway, REST catch-up and webhooks accepted 2026-10-10
0053 No JSON null in API and events accepted 2026-10-10
0054 Origin and trust marking of foreign content in the agent context accepted 2026-10-10
0055 Cost reconciliation as its own app, admin key never in the server accepted 2026-10-10
0056 Native extensions without the Flutter engine (NSE, share, Android push) accepted 2026-10-10
0057 Client telemetry through a server endpoint instead of a client OTel SDK accepted 2026-10-10
0058 Backup with pgBackRest, object backup and automatic restore test accepted 2026-10-10
0059 Sync epoch after restore accepted 2026-10-10
0060 Release automation in the monorepo accepted 2026-10-10
0061 Token format with a fixed prefix and checksum accepted 2026-10-10
0062 Release signatures while the repo is private accepted 2026-10-10
0063 Performance gate for the event log accepted 2026-10-10
0064 Feature flag registration with a cleanup gate accepted 2026-10-10
0065 Maintenance mode read_only accepted 2026-10-10
0066 Signing keys in the writable key store accepted 2026-10-10
0067 JOSE profile with the standard library instead of a JOSE library accepted 2026-10-10
0068 Terminal through a host service with a Noise end-to-end stream and invariant I6 accepted 2026-10-10
0069 Visualization on two levels without iframes in apps accepted 2026-10-10
0070 Terminal in the web console accepted 2026-10-10
0071 In-process test seams of serve accepted 2026-10-18
0072 Firebase messaging only in builds with a Firebase configuration accepted 2026-10-25