Julien Gautier
4af0269edf
post-auth-track état-des-lieux of docs/architecture.md. three
small lies caught, one diagram added.
containers (§2):
portal-admin (adr-0020) was missing from the c4 level-2 view
despite being scaffolded under apps/portal-admin and shipping
its own session cookie. added as a sibling spa on a distinct
origin with its own session (__host-portal_admin_session),
and the bff box now distinguishes /api/* (end-user) from
/api/admin/* (rbac + @requiremfa).
nx boundaries (§3):
- shared-ui was drawn under scope:portal-shell. its actual tag
in project.json is scope:shared. same for shared-state, which
wasn't on the diagram at all. both moved to the scope:shared
bubble.
- portal-admin absent. added with planned (dashed) edges to the
shared libs; no scope:portal-admin row exists yet in
eslint.config.mjs, that's a follow-up when admin modules grow.
- the "forbidden" examples framed shared-tokens ⟶ shared-ui as a
narrower-scope violation. both are scope:shared / type:shared,
so depConstraints actually permit it. replaced with examples
that are genuinely lint-enforced.
local dev infrastructure (§5, new):
visualises what `docker compose up` starts: postgres + redis +
otel-collector always-up, plus opt-in profiles dbtools (pgweb),
observability (jaeger), serve-static (caddy per adr-0019).
shows ports, named volumes, bring-up cheat sheet, and the
separate ci-runners stack (apf-portal-ci-runners, dedicated
network). source links point at the compose files so a
contributor chases details in one click.
to-be-added table:
trace-context-propagation row updated — its trigger ("first
observability instrumentation lands") was already met. now
flagged as overdue / pending a follow-up.
also carries the one-line mermaid syntax fix on §4's `squash`
node (parens-inside-label needed quoting). pre-existing local
edit.
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.