Julien Gautier
880c7ded6b
The host organisation - APF France Handicap - was confirmed on 2026-04-30. Update all in-repo references to use apf_portal (snake_case in prose) and apf-portal (kebab-case workspace name and repo URL). Touched: CLAUDE.md, ADRs 0001/0002/0003/0015, and the Nx bootstrap setup guide. The historical name is preserved as a single sentence in ADR-0003 as a self-validating example of the function-prefixed naming convention designed exactly for this scenario - the apps (portal-shell, portal-bff) and the lib conventions (feature-<name>, shared-<scope>) were unaffected by the rename, which was the explicit point of ADR-0003. Memory state aligned out-of-band: project_adastra.md retired, project_apf_portal.md created with the expanded APF context (host org, health + financial data scope, ASVS L3 pending RSSI input, UI stack decision spartan-ng + CDK + Tailwind, expanded phase-3 status). Pending follow-ups (user-side, not in this commit): - rename the Gitea repo julien/adastra_portal -> julien/apf_portal - git remote set-url origin gitea@git.unespace.com:julien/apf_portal.git - optionally rename the local working directory ~/Works/adastra_portal/ -> ~/Works/apf_portal/
63 lines
3.4 KiB
Markdown
63 lines
3.4 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-04-29
|
|
decision-makers: R&D Lead
|
|
tags: [process]
|
|
---
|
|
|
|
# Use ADRs to record architectural decisions
|
|
|
|
## Context and Problem Statement
|
|
|
|
Architecturally-significant decisions will be taken throughout the lifecycle of `apf-portal`. Without a written, durable trace of *why* a decision was made — context, drivers, alternatives, trade-offs — that knowledge fades within months. New contributors re-litigate settled debates, the rationale of constraints (security, performance, accessibility) gets lost, and reversing a choice later becomes risky because nobody remembers what it was protecting against.
|
|
|
|
How do we record decisions in a way that is light enough to be sustained, durable enough to outlive contributor turnover, and integrated into the development workflow?
|
|
|
|
## Decision Drivers
|
|
|
|
* Preserve the *why* of each decision so future contributors can understand or revisit it without re-deriving it.
|
|
* Make architecture reviewable — both at the time of a decision and during retrospective audits.
|
|
* Keep the format light enough that writing an ADR isn't a bureaucratic deterrent.
|
|
* Live alongside the code in version control, so decisions evolve with what they govern.
|
|
* Match the project's stated values: high technical bar, no bricolage, security/performance/accessibility as first-class concerns whose rationale must be traceable.
|
|
|
|
## Considered Options
|
|
|
|
* No formal records — rely on commit messages and tribal knowledge.
|
|
* External wiki / Confluence — decisions live outside the codebase.
|
|
* ADRs in markdown using the [MADR 4.0.0](https://github.com/adr/madr) format, in-repo.
|
|
* ADRs in another format (Nygard, Y-Statement, Cockburn).
|
|
|
|
## Decision Outcome
|
|
|
|
Chosen option: **ADRs in markdown using MADR 4.0.0**, stored in `decisions/` at the repository root.
|
|
|
|
Conventions are defined in [README.md](README.md):
|
|
- flat folder layout (no nested category folders);
|
|
- globally sequential 4-digit numeric prefix (`NNNN-kebab-title.md`);
|
|
- categorization via the `tags:` field in the MADR frontmatter, drawn from a canonical vocabulary;
|
|
- status lifecycle: `proposed` → `accepted` → optionally `deprecated` / `superseded by ADR-NNNN`;
|
|
- index maintained in [README.md](README.md) alongside any ADR change.
|
|
|
|
### Consequences
|
|
|
|
* Good, because the *why* of every architecturally-significant decision is captured at the moment it is made and travels with the code.
|
|
* Good, because ADRs are reviewed via the normal pull-request flow — architecture becomes an explicit team conversation.
|
|
* Good, because MADR provides enough structure (drivers, options, trade-offs) without being heavy.
|
|
* Good, because flat-folder + tags scales better than nested category folders as the count grows.
|
|
* Bad, because writing an ADR adds friction; this must be balanced against the cost of *not* writing one.
|
|
* Bad, because the index is maintained manually until tooling or a CI check is added.
|
|
|
|
### Confirmation
|
|
|
|
* Every change introducing or transitioning the status of an ADR updates the index table in [README.md](README.md) in the same commit.
|
|
* PR review explicitly checks for ADR proposal whenever a non-trivial decision is being introduced.
|
|
* (Future) A CI lint job validates filename pattern, frontmatter shape, and tag vocabulary.
|
|
|
|
## More Information
|
|
|
|
* MADR 4.0.0 specification: https://github.com/adr/madr
|
|
* General ADR resources: https://adr.github.io/
|
|
* Template: [template.md](template.md)
|
|
* Tag vocabulary: see "Tag vocabulary" in [README.md](README.md).
|