Julien Gautier
312791b74e
Cross-cutting visual reference for the architecture, written in Mermaid (text in markdown, rendered natively by Gitea / GitHub / IDE viewers, diffable in PR). Four diagrams that summarise decisions spread across multiple ADRs: 1. C4 level 1 - System Context. The portal as a black box with its workforce/customer/IT/RSSI actors and Entra ID + downstream APIs as external systems. Customer audience and Entra External ID are shown dashed (future scope per ADR-0008's dual-audience design). 2. C4 level 2 - Containers. Browser-side portal-shell, on-prem BFF, Postgres (public + audit schemas), Redis, local OTel Collector, plus external Entra ID and downstream APIs. Annotates the wire protocols (HTTPS + __Host- cookies, OIDC, OBO/signed assertion, OTLP, ioredis with AES-GCM at rest, traceparent end-to-end). 3. Nx module boundaries. The Project graph rendered with the depConstraints from ADR-0003 (scope axis: portal-shell / portal-bff / shared, plus type axis: app / feature / shared). Forbidden directions called out below the diagram. 4. CI/CD pipeline. Local hooks → push → PR → 5 parallel CI jobs (check / scan / commits / perf / a11y) → branch protection → squash-merge → tag → release. Includes the weekly scheduled security-scheduled.yml workflow (full-tree scan + prod Lighthouse). Convention adopted at the top of architecture.md: cross-cutting diagrams live here; single-ADR diagrams live inline in the ADR itself (sequence flows, ERDs, lifecycle diagrams, etc.). The 'To be added' section at the bottom maps each future diagram to where it will land and what triggers its addition. docs/README.md index updated with a new 'Architecture' section linking to architecture.md, and the previous empty 'Architecture' placeholder removed (the placeholder was a tick-the-box section that violated the doc convention 'documentation when genuinely useful, not just to tick a box').
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, 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.