Julien Gautier
0e58e32d29
Move the ADR folder under docs/ alongside the rest of the project
documentation. Convention (flat folder, globally-sequential 4-digit
numbering, tags-based categorization, MADR 4.0.0 format) is unchanged
- only the path moved.
- git mv decisions docs/decisions preserves history for all 18 ADRs +
README + template (19 files renamed in this commit).
- ADR-0001 amended in-place with a dated note documenting the
relocation. Status remains 'accepted' - the location detail
changed, the decision did not.
- All cross-references updated:
- CLAUDE.md (~17 ADR links + 3 mentions of decisions/ in the Project
rules section)
- docs/README.md (now references decisions/ as a sibling under docs/)
- docs/setup/03-angular-nx-monorepo.md (paths shortened from
../../decisions/ to ../decisions/, since setup/ and decisions/ are
now both inside docs/)
- docs/decisions/0003 ../CLAUDE.md adjusted to ../../CLAUDE.md
(one extra level of nesting)
- docs/decisions/template.md mention of the README path
- notes/asvs-level-decision-briefing-rssi.md mention of the index
Sanity verified: every ADR link in CLAUDE.md, docs/setup/03, and
docs/decisions/0001 resolves to an existing file. pnpm nx run-many
-t lint passes on 8 projects.
4.2 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.