Julien Gautier
79eee77594
Set up the foundation for the adastra-portal project: - CLAUDE.md captures durable project rules (quality bar, security/perf/a11y as first-class, language, commit conventions, ADR proactivity). - docs/ and decisions/ scaffolding with maintained indexes (docs/README.md and decisions/README.md), MADR 4.0.0 template, and tag vocabulary. - Phase-1 ADRs (0001-0006) lock structural choices: ADR usage, Nx monorepo with the apps preset, naming convention (adastra-portal / portal-shell / portal-bff), Angular CSR/zoneless/Signals/Vitest, NestJS over Express, PostgreSQL with Prisma. - docs/setup/ guides translated to English. - .gitignore covers Node/Nx artifacts and the personal notes/ scratchpad. The Nx workspace itself is not yet bootstrapped; that step is gated on a revised setup guide aligned with the ADRs.
3.4 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 adastra_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 —
adastra-front,adastra-back. Fragile to 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 | adastra-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). Even if the brand Adastra is renamed, "portal" remains accurate. The brand-ish token adastra 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.