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.
This commit is contained in:
Julien Gautier
@@ -0,0 +1,77 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project rules (durable)
|
||||
|
||||
These constraints were set by the project lead at kickoff. They apply to every change.
|
||||
|
||||
- **Scale & quality bar.** Treat this as a large-scale portal for a sizable organization, not a prototype. No bricolage, no exotic stacks. **Default to stable, recognized, battle-tested choices.** Cutting-edge / "à la pointe" alternatives must always be evaluated alongside the stable option, but are only adopted when the trade-off is captured in an ADR (drivers, risk, exit strategy). Pre-1.0 dependencies and one-maintainer projects are rejected unless an ADR justifies the exception.
|
||||
- **Security, performance, accessibility.** All three are first-class concerns from day one — never bolted on. Architecture, dependency, and feature decisions must explicitly consider their impact on these axes and document the trade-offs.
|
||||
- **Project name.** Currently `adastra_portal`, provisional. Do not hardcode it outside repo/workspace-level metadata so a rename stays a one-line change.
|
||||
- **Language.** All code, identifiers, comments, documentation, commit messages, and PR descriptions are written in **English**. (Conversation with the project lead happens in French — but artifacts shipped in the repo are English-only.)
|
||||
- **Commits / PRs.** Never add a `Co-Authored-By: Claude` trailer or a `🤖 Generated with Claude Code` footer to commits or PR bodies.
|
||||
- **Be a peer, not a typist.** Challenge requests when a better approach exists; surface trade-offs frankly. Don't silently execute a suboptimal directive — propose, then execute the agreed plan.
|
||||
|
||||
## Documentation
|
||||
|
||||
- All documentation lives in `.md` files under [docs/](docs/), indexed by [docs/README.md](docs/README.md). The index is **maintained automatically** whenever a doc is added, renamed, or removed — no need to be asked.
|
||||
- Documentation is written proactively whenever it is genuinely useful (architecture, runbooks, onboarding, security/perf/a11y rationales). It is **not** created for trivial things just to tick a box.
|
||||
- The folder [notes/](notes/) is the project lead's **personal scratchpad** — git-ignored and not part of project artifacts. Never write project documentation there.
|
||||
|
||||
## Architectural Decision Records (ADRs)
|
||||
|
||||
- Format: **MADR 4.0.0** (https://adr.github.io/, https://github.com/adr/madr). Template at [decisions/template.md](decisions/template.md).
|
||||
- Location: flat folder [decisions/](decisions/), indexed by [decisions/README.md](decisions/README.md).
|
||||
- Filename convention: `NNNN-kebab-title.md` with **globally sequential** 4-digit numbers. Numbers are never reset and never reused — even when an ADR is superseded or deprecated.
|
||||
- Categorization: via the `tags:` array in the MADR frontmatter (e.g. `[frontend, security]`). The canonical tag vocabulary lives in `decisions/README.md`; never invent ad-hoc tags inline.
|
||||
- **Proactivity.** Any non-trivial development decision (tool/library choice, framework pattern, security control, perf budget, a11y target, naming convention, deprecation, breaking change) warrants proposing an ADR before implementation. Don't wait to be asked. Update the index in the same change.
|
||||
|
||||
## Architecture (decided in phase-1 ADRs)
|
||||
|
||||
The structural choices are recorded as ADRs and summarized below. Any change to these requires updating the corresponding ADR.
|
||||
|
||||
- **Workspace:** Nx monorepo with the `apps` preset, managed by pnpm — see [ADR-0002](decisions/0002-adopt-nx-monorepo-apps-preset.md).
|
||||
- **Naming:** workspace `adastra-portal`; apps `portal-shell` (frontend) and `portal-bff` (backend); libs `feature-<name>` and `shared-<scope>` — see [ADR-0003](decisions/0003-workspace-and-app-naming-convention.md).
|
||||
- **Frontend (`portal-shell`):** Angular at the latest LTS major — standalone APIs, zoneless change detection, Signals, **CSR only (no SSR)**, Vitest, SCSS — see [ADR-0004](decisions/0004-frontend-stack-angular-csr-zoneless-signals.md).
|
||||
- **Backend (`portal-bff`):** NestJS at the latest stable major, mounted on the Express adapter (Fastify adapter swappable later) — see [ADR-0005](decisions/0005-backend-stack-nestjs.md).
|
||||
- **Persistence:** PostgreSQL (latest stable major) via Prisma — see [ADR-0006](decisions/0006-persistence-postgresql-prisma.md).
|
||||
- **Sessions / cache:** Redis self-hosted — to be locked-in by ADR-0009 (phase 2).
|
||||
- **Identity:** dual-audience Microsoft Entra (workforce + Entra External ID for customers), OIDC Auth Code + PKCE flow via `@azure/msal-node` — to be locked-in by ADRs 0007, 0008, 0010 (phase 2).
|
||||
- **Observability:** Pino structured logs + OpenTelemetry traces with W3C Trace Context propagation — to be locked-in by ADR-0012 (phase 2).
|
||||
- **Runtime:** Node.js latest LTS major.
|
||||
|
||||
## Repository status
|
||||
|
||||
The Nx workspace is **not yet bootstrapped** — there is no `package.json`, no source code, no tests. Phase-1 ADRs (0001 → 0006) have fixed the structural choices; the next step is to scaffold the workspace per a revised version of [docs/setup/03-angular-nx-monorepo.md](docs/setup/03-angular-nx-monorepo.md) (the existing file still carries the original placeholder values and needs an update to match the ADRs before it is followed).
|
||||
|
||||
If asked to "build", "test", or "run" anything, first verify whether the workspace exists; if not, the right response is to scaffold it (or update the setup doc), not to invent commands.
|
||||
|
||||
## Commands once the workspace exists
|
||||
|
||||
App-scoped — `<app>` is one of `portal-shell`, `portal-bff`:
|
||||
```bash
|
||||
pnpm nx serve <app> # dev server
|
||||
pnpm nx build <app>
|
||||
pnpm nx test <app> # Vitest, all tests for the app
|
||||
pnpm nx lint <app>
|
||||
```
|
||||
|
||||
Run a single test file:
|
||||
```bash
|
||||
pnpm nx test <app> --testFile=path/to/file.spec.ts
|
||||
```
|
||||
|
||||
Workspace-wide:
|
||||
```bash
|
||||
pnpm nx run-many -t lint test build
|
||||
pnpm nx affected -t lint test build # only projects affected by current changes
|
||||
pnpm nx format:check
|
||||
```
|
||||
|
||||
## Environment conventions
|
||||
|
||||
- **Never install Angular globally.** Use `pnpm dlx` for one-off CLI invocations and project-local `pnpm nx ...` for everything else — versions stay pinned per project.
|
||||
- **Work inside the WSL filesystem** (`~/dev/...`), never under `/mnt/c` — the latter has severe I/O penalties that break Nx caching and dev-server reload times.
|
||||
- **pnpm is mandatory** (activated via `corepack enable`); do not introduce npm or yarn lockfiles.
|
||||
- Prettier config target: `singleQuote: true`, `semi: true`, `printWidth: 100`.
|
||||
Reference in New Issue
Block a user