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.ADR-013 (MCP connector) is Proposed and acceptance is blocked on six critical findings from its five-lens red-team review, all verified against the code: the account-lifecycle guarantee behind SSO-only consent does not exist, the SSO step-up cannot complete against the current middleware and surface clamp, public client registration is a consent-phishing surface with no organisation-level policy, the consent decision is reachable with a bearer-transported session token, reusing the routes’ DTOs leaks sensitive and third-party-authored data, and the cross-border transfer to assistant vendors was misdescribed. A product gate (validated demand hypotheses, a self-service-only pilot with a stop rule) precedes Phase 1.

​
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.