Skip to content

Architecture decisions

An architecture decision record (ADR) states one decision that shapes the system: the problem, the options that were on the table, the choice, and what it costs. This is section 11 of the system documentation.

No. Decision Status Date
0001 Modular monolith Accepted 2026-11-12
0002 PostgreSQL with row level security per company Accepted 2026-11-12
0003 Gate schema with definer functions for paths without a session Accepted 2026-11-12
0004 Versioned migrations with Drizzle Accepted 2026-11-12
0005 REST with OpenAPI and a generated client Accepted 2026-11-12
0006 Worker with queues and work discovery per company Accepted 2026-11-13
0007 React with Vite for the product apps Accepted 2026-11-12
0008 Astro for the public sites Accepted 2026-11-12
0009 Monorepo with pnpm and Turborepo Accepted 2026-11-12
0010 Design system used only through tokens and components Accepted 2026-11-12
0011 Archive instead of delete Accepted 2026-11-12
0012 Single path for sending messages, with consent Accepted 2026-11-13
0013 External providers behind adapters, with a simulator Accepted 2026-11-13
0014 In-house electronic signature Accepted 2026-11-14
0015 Column encryption of sensitive data, with logged reveal Accepted 2026-11-14
0016 Separate vault for the drug and alcohol file Accepted 2026-11-14
0017 S3-compatible file storage Accepted 2026-11-12
0018 Public tokens stored only as hashes Accepted 2026-11-12
0019 Compliance rules as a regulatory preview Accepted 2026-11-12
0020 Documentation with Starlight at /docs Accepted 2026-11-15
0021 Hard delete of registers by default Superseded by ADR-0011 2026-11-12
0022 Text search through definer functions that return ids Accepted 2026-11-12
0023 Platform team as a separate identity behind staff functions Accepted 2026-11-12
0024 Opaque cookie sessions with origin checks Accepted 2026-11-12
0025 Domain events through a transactional outbox Accepted 2026-11-13
0026 Driver app as a progressive web app in version 1.0 Accepted 2026-11-12
0027 Shared platform services as modules of their own Accepted 2026-11-13
0028 UUID v7 keys and monthly partitions for high-volume tables Accepted 2026-11-12
0029 Demo environment on a single host with Docker Compose Accepted 2026-11-15

The records follow MADR (Markdown Architectural Decision Records). Every page has the same parts, in this order: status and date, “Context and problem statement”, “Decision drivers”, “Considered options”, “Decision outcome”, “Consequences” and “More information”. The status is “Proposed”, “Accepted” or “Superseded by ADR-NNNN”. “Considered options” lists only the options that were evaluated when the decision was made, or the common alternative in the market, marked as such. “More information” points to the code where the decision is applied and to the pages of this documentation that explain the concept.

A record is never rewritten to say something else. When a decision changes, a new record is written and the old one stays, with the status “Superseded by” and a link to its replacement.

Run scripts/docs.sh new adr "<decision>" from the root of the repository. It creates a file in apps/docs/src/content/docs/system/adr/, named with the next free four-digit number and a slug of the title (for example 0029-short-title.md), in the format above, with the status “Proposed”, the date of today and sidebar.order set to the number, and adds the row to the table above. Replace every placeholder text the template marks, then open it for review together with the change it supports; scripts/docs.sh check fails while the record is out of the format or a number is missing. When the change is merged the status becomes “Accepted”. If the new record replaces an older one, change the status of the older record in the same commit.