Files

T

Julien Gautier 880c7ded6b chore: rename project from adastra_portal to apf_portal

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/

2026-04-30 13:31:38 +02:00

3.4 KiB

Raw Blame History

status, date, decision-makers, tags

status

date

decision-makers

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 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:

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 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 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
Tag vocabulary: see "Tag vocabulary" in README.md.

3.4 KiB Raw Blame History