chore: relocate ADRs from decisions/ to docs/decisions/ to consolidate documentation

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.
2026-04-30 18:57:59 +02:00
parent bd8eefb44a
commit 0e58e32d29
27 changed files with 1653 additions and 1570 deletions
@@ -0,0 +1,61 @@
+---
+status: accepted
+date: 2026-04-29
+decision-makers: R&D Lead
+tags: [process]
+---
+
+# 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-bff` are 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-shell` vs `pnpm 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.json` and in each project's `project.json`.
+- `@nx/eslint/enforce-module-boundaries` is 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.
+
+## More Information
+
+- Related ADRs: [ADR-0002](0002-adopt-nx-monorepo-apps-preset.md), and the "Project name" rule in [CLAUDE.md](../../CLAUDE.md).