Julien Gautier
289a5bad09
CI / scan (pull_request) Successful in 2m31s
CI / commits (pull_request) Successful in 2m31s
CI / check (pull_request) Successful in 2m40s
CI / a11y (pull_request) Successful in 1m51s
Docs site / build (pull_request) Successful in 2m3s
CI / perf (pull_request) Successful in 6m11s
The development guide drifted as portal-admin shipped, the docs site
landed, and Prisma stayed pinned at 6.x. Surgical pass.
Section 1 (Repo layout):
* Add `apps/portal-admin/` and `apps/portal-admin-e2e/` — both
exist on `main` since #134.
* Drop the phantom `prisma.config.ts` (Prisma 6.x doesn't ship
one) and fix the "Prisma 7" tag to "Prisma 6.x" with the
ADR-0006 pin reference.
* Add `docs/index.md`, `docs/architecture.md`, `docs/.vitepress/`
+ new workflows (`docs-site.yml`, `renovate.yml`) so the layout
matches what `ls` actually shows.
Section 3 (Initial setup) — new diagram:
* Mermaid `flowchart` of the local-dev topology (host-side dev
servers + Compose containers + viewer profiles + the optional
docs site). Replaces the prose ports-table that was scattered
across §3 and §5 for new contributors.
Section 4 (Daily commands):
* Add `portal-admin` to serve / test / generate examples.
* Correct the single-test-file recipe — Nx's vitest executor
rejects `--testFile`; use positional `path/to/file.spec.ts`
for Vitest projects, `--testPathPattern=…` for Jest.
* New "Documentation site" subsection — `docs:dev` / `docs:build`
/ `docs:preview`, link to ADR-0022.
Section 5 (Observability):
* Mermaid `sequenceDiagram` of how a click becomes a trace
(browser span → traceparent → BFF span → Pino log line with
matching trace_id → OTLP batch → Jaeger). Anchors the
correlation rule that the prose explained but didn't visualise.
Section 6 (Renovate):
* Add "Transitive vulnerabilities — `pnpm.overrides`" subsection.
Documents the pattern from #159 (vite + esbuild via VitePress)
so the next contributor hitting a transitive vuln has the
playbook on hand.
Section 9 (Sections to come):
* Split into "Code shipped — doc to write" and "Not yet". Many
phase-2 items moved out of "to come" since the code has shipped
(auth, sessions, MFA decorator, admin module, audit viewer,
user directory, downstream strategies, OpenAPI tooling,
capabilities endpoint). The roadmap now reflects what's
actually still missing.
Documentation index
This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a .md file under docs/ must be reflected here in the same change.
Conventions
- Documentation is written in English.
- One topic per file. Group related files into a folder when there are three or more.
- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
- For architectural decisions, do not add them here — they belong in decisions/ as MADR 4.0.0 ADRs.
Sections
Daily development
- development.md — repo layout, prerequisites, initial setup, daily commands, observability dev-loop (Jaeger UI, log ↔ trace correlation), dependency updates (Renovate), conventional commit cycle. Day-to-day reference for working on the project.
Architecture
- architecture.md — cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. Single-decision diagrams (auth sequence, ERD, etc.) live inline in their ADR.
Onboarding & environment
Setup guides for new contributors:
- setup/01-wsl-terminal-setup.md — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
- setup/02-dev-web-stack.md — Node via nvm, pnpm via corepack, Docker
- setup/03-angular-nx-monorepo.md — Angular + Nx monorepo bootstrap
Operations & runbooks
Empty — to be populated when we deploy.
Security, performance, accessibility
Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs.