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').
Julien Gautier