Architecture decisions

The ADR index — what was decided, when, and what is still open.

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.

#	Decision	Status
001	Next.js App Router	Accepted
002	Prisma as ORM	Accepted
003	EUPL v1.2 license	Accepted
004	Module architecture	Accepted
005	In-process event bus	Accepted
006	Compassionate Systems Framework	Accepted (2026-04-25)
007	Prisma.Decimal for the payroll engine	Accepted (2026-05-21)
008	PageIndex for document intelligence	Proposed — spike landed, MVP pending
009	Versioned portal API contract	Accepted (phased)
010	Multiple legal entities within a tenant	Accepted (amended 2026-07-05)
011	Applicant↔Employee identity and lifecycle	Accepted (2026-07-09)
012	Surface architecture — portal, dashboard, iOS	Proposed — acceptance blocked

The ones that shape day-to-day work

ADR-004 — Module architecture

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.

ADR-005 — In-process event bus

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.

ADR-006 — Compassionate Systems Framework

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.

ADR-007 — Decimal payroll arithmetic

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.

ADR-009 — Versioned portal API contract

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.

ADR-010 — Multiple legal entities

One installation can employ through several Rechtsträger. The entity routes every statutory declaration, which is why write paths must resolve it explicitly. See Legal entities.

ADR-011 — One User for the whole lifecycle

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.