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/
3.6 KiB
status, date, decision-makers, tags
| status | date | decision-makers | tags | |
|---|---|---|---|---|
| accepted | 2026-04-29 | R&D Lead |
|
Workspace and app naming convention
Context and Problem Statement
Default Nx scaffolding offers placeholder names like my-workspace and web, which are unacceptable for a long-lived enterprise project. Naming has to survive two foreseeable changes: the product's marketing name may evolve (the working title apf_portal is provisional), and the project may sit alongside other R&D projects in the same Gitea organization, where collisions on generic names like web or api would cause confusion.
What naming convention do we adopt for the workspace, the apps, and future libraries so names are explicit, function-anchored, and stable against rebranding?
Decision Drivers
- The product's marketing name is provisional — names anchored on it become stale at rebrand.
- Names should reflect function, not brand.
- Multiple R&D projects may share the org — generic names (
web,api,frontend) cause friction. - Compliance with npm package naming rules (lowercase, kebab-case).
- Readability inside Nx's project graph and CLI output.
Considered Options
- Defaults —
my-workspace,web. (Rejected up-front.) - Brand-anchored —
apf-front,apf-back. Fragile to further rebranding. - Function-prefixed —
portal-shell,portal-bff. (Chosen.) - Generic —
shell,bff. Risk of org-wide collision; reduced readability.
Decision Outcome
Chosen option: function-prefixed naming.
| Scope | Name | Rationale |
|---|---|---|
| Workspace / repo / npm package root | apf-portal |
matches the Gitea repository name; the only place a brand-ish name lives, so a rebrand is a one-line change |
| Frontend app | portal-shell |
"shell" describes the function — the Angular host that loads features |
| Backend app | portal-bff |
explicit role: backend-for-frontend |
| Feature libraries | feature-<name> |
e.g. feature-auth, feature-billing |
| Shared libraries | shared-<scope> |
e.g. shared-ui, shared-data-access, shared-util |
The portal- prefix encodes the function (a portal). The host organisation's brand can change without invalidating "portal" — the project was originally proposed as adastra_portal and renamed to apf_portal on 2026-04-30 once the host organisation (APF France Handicap) was confirmed; the apps portal-shell / portal-bff were unaffected by the rename, validating this convention. The brand-ish token apf is confined to the workspace root and a tiny number of metadata files (root package.json, repo URL).
Consequences
- Good, because names survive a brand change with minimal churn.
- Good, because
portal-shell/portal-bffare unambiguous in CLI output and in the Nx project graph. - Good, because the prefix scales when more apps appear (e.g.
portal-admin,portal-jobs). - Bad, because the prefix adds verbosity (
pnpm nx serve portal-shellvspnpm nx serve web). Acceptable. - Neutral, because if "portal" itself ceases to be accurate (e.g. the system pivots to something other than a portal), the prefix would also need updating — but that would be a deeper architectural pivot anyway.
Confirmation
- Nx project names match the convention in
nx.jsonand in each project'sproject.json. @nx/eslint/enforce-module-boundariesis configured with tags aligned to the convention (scope:portal-shell,scope:portal-bff,type:feature,type:shared).- PR review rejects new project names that don't match.