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/
62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
---
|
|
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).
|