julien/apf_portal
1
0
Fork 0
Code Issues 1 Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add docs/architecture.md with C4 contexts, Nx boundaries, and CI/CD pipeline #1

Merged
julien merged 2 commits from docs/architecture-diagrams into main 2026-05-01 00:45:23 +02:00
Conversation 0 Commits 2 Files Changed 3
+231 -4
julien commented 2026-04-30 23:21:52 +02:00
Owner
Copy Link
Copy Source

Summary

  • Add docs/architecture.md with four cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline.
  • Add an inline OIDC Authorization Code + PKCE sequence diagram at the top of ADR-0009's Decision Outcome (5 participants, 13 autonumbered steps).
  • Update docs/README.md index: new Architecture section linking to docs/architecture.md, and remove the empty Architecture placeholder section that violated the project's "documentation when genuinely useful" convention.

Motivation

  • ADRs capture the why of each decision but don't deliver the cross-cutting visual that helps a contributor, the RSSI, the IT contact, or an external auditor build a fast mental model of the system.
  • Establishes the doc/diagram convention going forward: cross-cutting diagrams in docs/architecture.md, single-decision diagrams inline in the ADR they visualise. Encoded at the top of the new file.
  • Cleans up a tick-the-box placeholder section in the doc index per the documentation rule in CLAUDE.md.

Implementation notes

  • Diagrams written in Mermaid — text-in-markdown, rendered natively by Gitea / GitHub / most IDE markdown viewers, diffable in PR review. No binary, no external renderer. Aligned with the project's "no exotic stack" rule.
  • Only standard Mermaid syntax used (flowchart, sequenceDiagram with autonumber, classDef for styling). No experimental features.
  • Each diagram annotates its source ADRs so a reader can click through to the decision rationale.
  • The To be added table at the bottom of architecture.md maps every future diagram (trace context propagation, dual-audience flow, step-up MFA, ERD, audit lifecycle, downstream call lifecycle, trust boundaries) to the implementation work that triggers its addition. Same pattern as docs/development.md §7's roadmap.
  • The ADR-0009 sequence diagram is placed at the top of Decision Outcome, before the textual breakdown, so it serves as a visual recap that the prose then details (library / flow / tokens / validation / refresh / cookies / CSRF / routes / auth layer).

Verification

  • pnpm ci:check — markdown-only change; CI will run on PR open. No code paths exercised.
  • pnpm ci:audit — unchanged, no new dependency added.
  • Tested manually — Mermaid blocks were authored against the standard syntax reference; visual rendering to be confirmed via Gitea's PR view, VS Code's Markdown Preview Mermaid Support extension, or mermaid.live.
  • Architecture diagram updated — this PR is the architecture-diagram introduction.
  • ADR amended — ADR-0009 gains a visual aid; no status change, no decision change.

Related

  • ADR-0009 (auth flow) — gains the inline sequence diagram. Decision content unchanged.
  • ADRs summarised in docs/architecture.md (cross-references inside each diagram block): 0002, 0003, 0004, 0005, 0006, 0007, 0008, 0010, 0012, 0013, 0014, 0015, 0016, 0017.
  • Follow-up diagrams scheduled per the To be added table in docs/architecture.md.
## Summary - Add `docs/architecture.md` with four cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. - Add an inline OIDC Authorization Code + PKCE sequence diagram at the top of ADR-0009's *Decision Outcome* (5 participants, 13 autonumbered steps). - Update `docs/README.md` index: new *Architecture* section linking to `docs/architecture.md`, and remove the empty *Architecture* placeholder section that violated the project's "documentation when genuinely useful" convention. ## Motivation - ADRs capture the *why* of each decision but don't deliver the cross-cutting visual that helps a contributor, the RSSI, the IT contact, or an external auditor build a fast mental model of the system. - Establishes the doc/diagram convention going forward: **cross-cutting diagrams in `docs/architecture.md`, single-decision diagrams inline in the ADR they visualise**. Encoded at the top of the new file. - Cleans up a tick-the-box placeholder section in the doc index per the documentation rule in CLAUDE.md. ## Implementation notes - Diagrams written in [Mermaid](https://mermaid.js.org/) — text-in-markdown, rendered natively by Gitea / GitHub / most IDE markdown viewers, diffable in PR review. No binary, no external renderer. Aligned with the project's "no exotic stack" rule. - Only standard Mermaid syntax used (`flowchart`, `sequenceDiagram` with `autonumber`, `classDef` for styling). No experimental features. - Each diagram annotates its source ADRs so a reader can click through to the decision rationale. - The *To be added* table at the bottom of `architecture.md` maps every future diagram (trace context propagation, dual-audience flow, step-up MFA, ERD, audit lifecycle, downstream call lifecycle, trust boundaries) to the implementation work that triggers its addition. Same pattern as `docs/development.md` §7's roadmap. - The ADR-0009 sequence diagram is placed at the top of *Decision Outcome*, before the textual breakdown, so it serves as a visual recap that the prose then details (library / flow / tokens / validation / refresh / cookies / CSRF / routes / auth layer). ## Verification - [ ] `pnpm ci:check` — markdown-only change; CI will run on PR open. No code paths exercised. - [ ] `pnpm ci:audit` — unchanged, no new dependency added. - [ ] Tested manually — Mermaid blocks were authored against the standard syntax reference; visual rendering to be confirmed via Gitea's PR view, VS Code's Markdown Preview Mermaid Support extension, or [mermaid.live](https://mermaid.live). - [x] Architecture diagram updated — *this PR is the architecture-diagram introduction.* - [ ] ADR amended — ADR-0009 gains a visual aid; no status change, no decision change. ## Related - ADR-0009 (auth flow) — gains the inline sequence diagram. Decision content unchanged. - ADRs summarised in `docs/architecture.md` (cross-references inside each diagram block): [0002](docs/decisions/0002-adopt-nx-monorepo-apps-preset.md), [0003](docs/decisions/0003-workspace-and-app-naming-convention.md), [0004](docs/decisions/0004-frontend-stack-angular-csr-zoneless-signals.md), [0005](docs/decisions/0005-backend-stack-nestjs.md), [0006](docs/decisions/0006-persistence-postgresql-prisma.md), [0007](docs/decisions/0007-pre-commit-hooks-and-conventional-commits.md), [0008](docs/decisions/0008-identity-model-entra-workforce-dual-audience.md), [0010](docs/decisions/0010-session-management-redis.md), [0012](docs/decisions/0012-observability-pino-opentelemetry.md), [0013](docs/decisions/0013-audit-trail-separated-postgres-append-only.md), [0014](docs/decisions/0014-downstream-api-access-obo-pattern.md), [0015](docs/decisions/0015-cicd-gitea-actions.md), [0016](docs/decisions/0016-accessibility-baseline-wcag-aa-targeted-aaa.md), [0017](docs/decisions/0017-performance-budgets-lighthouse-ci.md). - Follow-up diagrams scheduled per the *To be added* table in `docs/architecture.md`.
julien added 2 commits 2026-04-30 23:21:52 +02:00
docs: add docs/architecture.md with C4 contexts, Nx boundaries, and CI/CD pipeline 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').
docs: add inline OIDC sequence diagram to ADR-0009
CI / commits (pull_request) Failing after 2s
Details
CI / check (pull_request) Failing after 3s
Details
CI / scan (pull_request) Failing after 6s
Details
CI / a11y (pull_request) Failing after 3s
Details
CI / perf (pull_request) Failing after 3s
Details
4b8d0789b1 
Render the OAuth 2.0 Authorization Code + PKCE flow as a Mermaid
sequence diagram at the top of the Decision Outcome section. Five
participants (user, SPA, BFF, Entra, Redis), thirteen autonumbered
steps covering the authorize redirect, the user-side authentication
(with the Conditional Access MFA enforcement annotated), the
callback, the state verification, the token exchange, the id_token
validation pipeline (signature, iss against the tenant allowlist,
aud, exp/nbf, amr sanity-check, audience-claim mapping), the
encrypted session write to Redis, and the cookie set.

Inline rather than in docs/architecture.md per the convention stated
at the top of architecture.md: cross-cutting diagrams live in the
architecture file, single-decision diagrams live inside the ADR they
visualise. ADR-0009 IS the auth flow decision; the sequence diagram
belongs here.

Cross-references the related ADRs (0010 sessions, 0011 MFA, 0008
audience model) so the diagram reads as the integration point of
the security stack rather than as an isolated picture.
julien merged commit f0b437bdc9 into main 2026-05-01 00:45:23 +02:00
julien deleted branch docs/architecture-diagrams 2026-05-01 00:45:25 +02:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adastra-bot (AdAstra Bot) julien (Julien Gautier)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: julien/apf_portal#1
Delete Branch "docs/architecture-diagrams"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?