chore: initialize repository with project rules, docs, and phase-1 ADRs

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.
2026-04-29 20:43:00 +02:00
commit 79eee77594
15 changed files with 1170 additions and 0 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 `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-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).