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.
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