Architecture Decision Records
Each ADR captures one significant technical decision — its context, what was decided, and the trade-offs accepted. They are listed here in causal order: the foundational choices first, then the ones that build on them.
| ADR | Decision | Theme |
|---|---|---|
| 001 | Hexagonal (ports & adapters) architecture, enforced by ArchUnit | Backend structure |
| 002 | Reactive stack: Spring WebFlux + R2DBC | Backend runtime |
| 003 | Kotlin on the JVM with a Java 25 toolchain | Language |
| 004 | Delegated authentication via OIDC (resource server + confidential client) | Security |
| 005 | Database-driven, project-scoped RBAC via a custom PermissionEvaluator | Authorization |
| 006 | PostgreSQL with Flyway migrations and pg_trgm trigram search | Persistence |
| 007 | Keeping (and documenting) the inverted in/out adapter naming | Convention |
| 008 | Frontend runtime configuration injection (one immutable image) | Frontend delivery |
| 009 | NGXS for frontend state management | Frontend state |
| 010 | Distroless container delivery with semantic-release | Build & release |
| 011 | Frontend framework: Vue 3 on Nuxt (replacing Angular) | Frontend framework |
| 012 | Rendering strategy: server-side rendering on Nuxt | Frontend rendering |
| 013 | Design system: Ant Design Vue (replacing PrimeNG) | Frontend UI |
| 014 | Frontend state: Pinia + facades (supersedes 009) | Frontend state |
| 015 | Accessibility: WCAG 2.2 AA (formalizable to EN 301 549 / EAA) | Accessibility |
| 017 | API v2 naming, query conventions, and v1 sunset | API contract |
| 018 | Backend caching (Caffeine in-process) and database optimization | Performance |
| 019 | Backend security hardening: rate limiting, session/token policy, audit logging | Security |
| 020 | Frontend observability: OpenTelemetry → Prometheus/Grafana | Observability |
| 021 | Test strategy and Angular→Vue parity (Playwright) | Quality |
| 022 | Full BFF: Nuxt OIDC client, Spring private resource server (amends 004) | Security |
| 023 | Runtime configuration on Nuxt (revises 008) | Frontend delivery |
| 024 | Frontend-tier security: CSP, cookies, CSRF, headers | Security |
Migration ADRs — review outcome (see the Migration Plan). The frontend rewrite is committed: ADRs 011/012/013/014/022/023 were promoted to Accepted (the Phase-0 spike now de-risks implementation rather than gating the decision). 024 is Accepted with a committed CSP baseline (strict
script-srcnonce; pragmaticstyle-src, upgradeable to fully-strict if the spike shows AntD styles can be nonced). All 13 migration ADRs (011–015, 017–024) are now Accepted. ADR 016 (frontend data/caching) was removed; the data layer is Nuxt built-ins, folded into implementation. Supersessions/revisions: 009→014 (Pinia), 008→023 (Nuxt runtime config), 004 amended by 022 (full-BFF auth); 024 is the frontend half of the security work in 019.
Format
Every record follows the same shape:
# ADR NNN — Title
## Status
Accepted | Superseded by ADR NNN | Deprecated
## Context
What problem or constraint triggered this decision?
## Decision
What was decided?
## Consequences
Positive and negative trade-offs, and why the alternatives were rejected.