> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<AccordionGroup>
  <Accordion title="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](/development/project-structure).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/concepts/design-philosophy).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/api-reference/introduction).
  </Accordion>

  <Accordion title="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](/concepts/legal-entities).
  </Accordion>

  <Accordion title="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](/concepts/surfaces).
  </Accordion>
</AccordionGroup>

## Open decisions

<Warning>
  **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.
</Warning>

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