Skip to main content
Architecture decision records live in docs/adr/ in the repository. They record the context, the decision, and the consequences — including the ones that turned out to be expensive.

​
The ones that shape day-to-day work

Features live in src/modules/{module}/ and expose a curated index.ts contract. Cross-module imports go through the contract, never into another module’s internals. See Project structure.
Modules communicate by emitting and listening to {module}.{entity}.{action} events rather than by importing each other. The pre-boarding orchestrator is the reference implementation.
The product’s design philosophy, and a list of things that will not be built. It overrides other guidance when they conflict. See Design philosophy.
All CHF math is decimal end to end. Floating point produced reproducible drift on hourly proration, four-decimal QST tariffs, and twelve-month booking aggregates. Rounding at the boundary does not recover it.
The OpenAPI specification is generated from the Zod schemas and verified byte-for-byte in CI. The mobile app regenerates its client from it. See API reference.
A person is one User row from applicant to alumnus. Applicant data and employee data hang off the same identity. See Surfaces.

​
Open decisions

ADR-008 (document intelligence) is Proposed. The spike is implemented — tree construction and reasoning-based search — but persistence, access control, i18n, an API route and a UI are MVP follow-ups.ADR-012 (surface architecture) is Proposed and acceptance is blocked on two critical findings the ADR itself records: terminated privileged users retaining dashboard access, and the landing predicate needing to be unified on a lifecycle-aware resolver. The direction survived a four-lens red-team review; the specific mechanism — surface as a pure function of User.role — did not.

​
Writing an ADR

Write one when a decision commits future effort, reverses a prior choice, or would otherwise have to be re-litigated from memory. Include:
  1. Status — Proposed, Accepted, Superseded — with a date and a change log.
  2. Context — what is actually true today, verified rather than assumed.
  3. Decision — what was chosen, and what was rejected.
  4. Consequences — including the costs.
An ADR whose “Context” section is speculation is a proposal, not a record. ADR-012 is a good model for the amended form: the red-team findings are folded in rather than appended, and the blockers are stated in the status line where they cannot be missed.