apf_portal

Author	SHA1	Message	Date
julien	670f6303fe	docs(adr-0028): accept CI/CD + git hosting migration to GitLab (#227 ) CI / check (push) Successful in 2m0s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m22s Details CI / a11y (push) Successful in 3m11s Details CI / perf (push) Successful in 6m15s Details Docs site / build (push) Successful in 5m11s Details ## Summary Promotes [ADR-0028](docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md) from `proposed` to `accepted`. Shipped as `proposed` in [#226](#226); no open question left on either drivers, considered options, or the 4-phase migration sequence. Same shape as [#219](#219) (ADR-0026 + ADR-0027 acceptance). Once merged, Phase 1 of the migration (`mirror-and-bootstrap` — repos pushed to GitLab, branch protection / MR templates / deploy keys / Renovate reconfig) is unblocked. ## What lands \| File \| Change \| \| --- \| --- \| \| `docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md` \| Frontmatter `status: proposed → accepted`. \| \| `docs/decisions/0015-cicd-gitea-actions.md` \| Status-update note added at the top, right under the title — calls out that the platform choice "Gitea Actions" is superseded by ADR-0028, while the rest of ADR-0015's architectural principles (trunk-based + squash, all-gates-blocking, thin YAML, on-prem runners, signed commits, Conventional Commits) carry over unchanged. ADR-0015 stays `accepted`. \| \| `docs/decisions/README.md` \| ADR-0028 row: `proposed → accepted`. \| \| `CLAUDE.md` \| Roll-up bumped to `ADRs 0001 → 0028 accepted` with a one-sentence explanation that ADR-0028 supersedes only ADR-0015's platform choice. CI/CD architecture bullet rewritten to reflect the accepted-but-not-yet-implemented state — "Gitea Actions today, migrating to GitLab CE on `vm-gitlab` per ADR-0028 (4-phase rollout in follow-up PRs)". The architectural detail (gates list, thin YAML, signed commits) was preserved; only the platform headline and the act_runner→GitLab Runner line are touched. Also corrected: `ci:scan` (which doesn't exist as a script) → the real script names (`ci:catalogue-drift`, `ci:audit`, `ci:perf`, `ci:gzip-budgets`). \| ## Notes for the reviewer - No new Architecture bullet for ADR-0028 itself. The decision is a platform shift for the existing CI/CD architecture, not a new architectural concern — so it folds into the existing ADR-0015 bullet rather than adding a sibling. - The annotation pattern on ADR-0015 (status-update blockquote at the top) is the canonical MADR way to handle partial supersession without changing the frontmatter status. The architectural principles are still accepted; only the platform implementation moves. A future reader hitting ADR-0015 first sees the redirect immediately. - The CLAUDE.md script-list correction is a side-fix — `ci:scan` is not a real script name; the actual gates are `ci:check`, `ci:catalogue-drift`, `ci:audit`, `ci:commits`, `ci:perf`, `ci:gzip-budgets`. Updated in the same touch since the bullet was being rewritten anyway. - No code changes, so no `pnpm ci:check` impact. `pnpm exec prettier --check` clean on the four touched files. ## Test plan - [x] `pnpm exec prettier --check` — clean on the four touched files. - [x] ADR-0015 → ADR-0028 cross-reference resolves (the new blockquote link). - [x] `ADRs 0001 → 0028 accepted` matches reality (`grep '^status: ' docs/decisions/.md` shows everything below 0029 as `accepted`). - [ ] Review focus* — the ADR-0015 status-update note phrasing, the CLAUDE.md CI/CD bullet rewrite (especially the "carry over" wording), the roll-up sentence about partial supersession. ## What's next (post-merge) 1. Phase 1 — `mirror-and-bootstrap` — `git push --mirror gitlab` for `apf_portal` and the proto vendoring in `apf-ai-service`. GitLab side: groups, projects, branch protection (mirror Gitea's), MR templates, deploy keys, Renovate reconfigured for GitLab. No `.gitlab-ci.yml` yet — Gitea pipelines continue to gate. Ops work primarily; the only PR-shaped output is a Renovate config update on the apf-portal repo if its host detection changes. 2. Phase 2 — `gitlab-ci-pipeline` — `.gitlab-ci.yml` lands alongside `.gitea/workflows/ci.yml`. Both pipelines run in parallel for ~1 calendar week. GitLab Runner registered on `vm-gitlab`. 3. Phase 3 — `cutover` — remotes flip in CLAUDE.md, READMEs, `docs/setup/01-dev-debian-vm-setup.md` §8.3. `.gitea/workflows/` + `infra/ci-runners.compose.yml` deleted, Gitea read-only / archive. 4. Phase 4 — `cleanup` — stale references sweep, required signed-commits on `main` enabled. In parallel — once you've finished walking through the dev VM bootstrap — the paused ADR-0027 PR 1 (Region / Delegation / Structure Prisma schema + inline seed) and ADR-0026 PR 1 (Person / User / UserScope schema + provisioner) can ship on Gitea; they're decoupled from the migration and don't need to wait for it. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #227	2026-05-26 10:54:55 +02:00
julien	04ee535de9	docs(adr-0028): propose CI/CD + git hosting migration Gitea -> GitLab (#226 ) CI / check (push) Successful in 3m28s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 3m3s Details CI / a11y (push) Successful in 4m21s Details CI / perf (push) Successful in 6m6s Details Docs site / build (push) Successful in 5m59s Details ## Summary Drafts [ADR-0028](docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md) as `proposed`: migrate CI/CD + git hosting from Gitea (`git.unespace.com`) to GitLab CE self-hosted on `vm-gitlab` (`10.100.201.10`). The migration was anticipated by [ADR-0015](docs/decisions/0015-cicd-gitea-actions.md) ("level-2 implementation; will be superseded by a GitLab migration ADR within 6-18 months") — that window opens now. Decision-only PR — the actual 4-phase migration ships across follow-up PRs after acceptance. ADR-0028's number was previously a placeholder reference in ADR-0026 and ADR-0027 for the Pléiades + Acteurs+ sync ADR. Renumbering: that future sync ADR shifts to `ADR-0029`, and the placeholder links in ADR-0026, ADR-0027 and `CLAUDE.md` update to match — included in the same PR so the chain stays consistent. ## What lands \| File \| Change \| \| --- \| --- \| \| `docs/decisions/0028-migrate-cicd-and-git-hosting-to-gitlab.md` \| New. MADR 4.0.0 ADR, `proposed`. Decision = Option B (GitLab CE on `vm-gitlab`). Considered options A (status quo Gitea), C (Forgejo), D (cloud SaaS). Documents what carries over from ADR-0015 (architectural principles unchanged — thin YAML, trunk-based, all-gates-blocking, on-prem runners), what changes (host, pipeline file, runner type, scan tooling), the 4-phase migration sequence, and the signed-commits revisit. \| \| `docs/decisions/0026-person-user-portal-data-model.md` \| All 11 `ADR-0028` references → `ADR-0029` (sync + facets shifts to 0029). \| \| `docs/decisions/0027-portal-side-organisational-hierarchy.md` \| All 14 `ADR-0028` references → `ADR-0029`. \| \| `docs/decisions/README.md` \| New row for ADR-0028 (`proposed`, tags `infrastructure`, `process`, 2026-05-26). \| \| `CLAUDE.md` \| Roll-up updated: `ADRs 0001 → 0027 accepted; ADR-0028 + ADR-0029 proposed`. ADR-0028's relationship to ADR-0015 spelled out inline ("supersedes ADR-0015's Gitea Actions platform choice — the rest of ADR-0015's architectural principles carry over unchanged"). ADR-0026 + ADR-0027 architecture bullets renumbered 0028 → 0029 to track. \| ## Key choices in the ADR - What carries over from ADR-0015 vs what changes — explicit table so future readers see immediately that the migration is platform-only, not a re-litigation of CI principles. Trunk-based + squash, all-gates-blocking, thin YAML over portable scripts (`pnpm ci:check` etc. — unchanged), on-prem runners, Conventional Commits in CI + hook (defense in depth) — all carried over. Host, pipeline-file grammar, runner type, and scan tooling are the only things that move. - Native security scanning replaces the manual Trivy + gitleaks setup. GitLab CE's built-in `Dependency-Scanning.gitlab-ci.yml` + `Secret-Detection.gitlab-ci.yml` includes consolidate the ~30 lines of inline `curl + tar` install dance currently in `.gitea/workflows/ci.yml`. Same blocking thresholds (CRITICAL+HIGH dependency vulns, any secret). - `vm-gitlab` is already provisioned. No infra wait — the only sequencing constraint is operator-driven, not infrastructure-driven. - 4-phase migration, parallel pipelines for ~1 week before cutover. Phase 1 mirrors repos and bootstraps GitLab side (no `.gitlab-ci.yml` yet — Gitea still gates). Phase 2 lands `.gitlab-ci.yml` alongside `.gitea/workflows/ci.yml` so both pipelines run per PR until parity is confirmed. Phase 3 flips the remote URLs and deletes `.gitea/workflows/` + `infra/ci-runners.compose.yml`. Phase 4 sweeps stale references. - Gitea moves to read-only / archive, not decommissioned at cutover. Existing references to Gitea PRs (`#213`, `#217`, `#219`, …) in commit messages and ADR bodies stay resolvable as historical artefacts. One VM at idle is a low long-term cost. - Signed commits revisit. ADR-0015 noted "signed commits recommended, revisited at GitLab migration". ADR-0028 makes the recommendation: enable required signed commits on `main` once GitLab is live, paired with GnuPG agent forwarding (already documented in `docs/setup/01-dev-debian-vm-setup.md` §8.5). `apf-portal-bot` (Renovate) gets a dedicated signing key at PR 1. ## Renumbering — what moved and why Before this PR, ADR-0026 and ADR-0027 used `ADR-0028` as a placeholder link for the Pléiades + Acteurs+ sync ADR. That sync ADR hasn't been drafted yet — the number was reserved. This PR claims `ADR-0028` for the GitLab migration (the immediately-actionable decision), and shifts the sync placeholder to ADR-0029. All 25 link references across ADR-0026 (11) and ADR-0027 (14) update in lockstep — replace_all is safe here because in those files `ADR-0028` consistently meant "the sync ADR". Content of the sync ADR is unchanged — only the number. When that ADR is eventually drafted as `0029-…md`, it gets the existing content reserved for it in the placeholder text. ## Test plan - [x] `pnpm exec prettier --check` clean on the touched files. - [x] All `ADR-0028` references in `0026-…md` / `0027-…md` / `CLAUDE.md` now read `ADR-0029` (grep confirms zero remaining references to the old number in those files). - [x] The new `0028-…md` self-references (status frontmatter, title, internal anchors) are consistent — no leftover `0029`. - [ ] Review focus — drivers / consequences / migration sequence in the ADR; the "what carries over from ADR-0015" table; the renumbering rationale. ## What's next Per ADR-0028 §"Migration sequence", post-acceptance: 1. ADR-0028 acceptance PR — small status-flip, same pattern as #219 (ADR-0026 + ADR-0027 acceptance). 2. `mirror-and-bootstrap` PR — `git push --mirror` Gitea → GitLab; GitLab side groups / projects / branch protection / MR templates / deploy keys / Renovate reconfig. No `.gitlab-ci.yml` yet, Gitea pipelines still gate. 3. `gitlab-ci-pipeline` PR — `.gitlab-ci.yml` alongside the existing `.gitea/workflows/ci.yml`. Parallel runs ~1 week for parity. GitLab Runner registered on `vm-gitlab`. 4. `cutover` PR — remotes flip across docs, `.gitea/workflows/` + `infra/ci-runners.compose.yml` deleted, Gitea read-only. 5. `cleanup` PR — stale references sweep, signed-commit policy finalised on `main`. In parallel — once the dev VM (#220 / #221 / #222 / #223 / #224) is fully bootstrapped — the paused ADR-0027 PR 1 (Region / Delegation / Structure Prisma schema + inline seed) and ADR-0026 PR 1 (Person / User / UserScope schema + provisioner) can ship on Gitea; they have no dependency on the GitLab migration and don't need to wait. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #226	2026-05-26 10:30:19 +02:00
julien	0d8b3712fb	docs(adr): accept ADR-0026 + ADR-0027 (#219 ) CI / check (push) Successful in 3m9s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m57s Details CI / a11y (push) Successful in 3m20s Details CI / perf (push) Successful in 4m48s Details Docs site / build (push) Successful in 5m0s Details ## Summary Promotes [ADR-0026](docs/decisions/0026-person-user-portal-data-model.md) and [ADR-0027](docs/decisions/0027-portal-side-organisational-hierarchy.md) from `proposed` to `accepted`. Both shipped as `proposed` in #217 after the cascade / acteurs_plus source-of-truth audit reshaped the org-hierarchy model. No open questions left on either. No code changes — same shape as #205 (ADR-0025 acceptance). ## What lands \| File \| Change \| \| --- \| --- \| \| `docs/decisions/0026-person-user-portal-data-model.md` \| Frontmatter `status: proposed → accepted`. \| \| `docs/decisions/0027-portal-side-organisational-hierarchy.md` \| Frontmatter `status: proposed → accepted`. \| \| `docs/decisions/README.md` \| Rows for 0026 and 0027 flip to `accepted`. \| \| `CLAUDE.md` \| Roll-up bumped to `0001 → 0027 accepted`; two new Architecture bullets ("Portal-side identity model" and "Portal-side organisational hierarchy") added after the ADR-0025 bullet; ADR-0025's bullet adjusted to clarify the scope literal `etablissement:<structure-code>` (with a pointer to ADR-0027 for the `Structure.code` semantics); the `@RequireScope` Prisma-resolver roadmap entry now references both ADRs as accepted with the two-schema-then-resolver phasing. \| ## Notes for the reviewer - ADR-0025's bullet got a small touch-up, not a rewrite. The original copy listed scope kinds as `etablissement:<finess>`, which was accurate when ADR-0025 shipped but is now superseded by ADR-0027's `Structure.code` semantics (FINESS for medico-social rows, internal slugs otherwise). The change is `<finess>` → `<structure-code>` + a `see ADR-0027` parenthetical. No actual decision in ADR-0025 changes. - Two new Architecture bullets, mirrored on the ADR-0024 / ADR-0025 pair of bullets that precede them in tone + length. The "Portal-side identity model" bullet calls out the `entraOid`-only v1 dedup and the non-unique `Person.email` (both decisions made during the split rework); the "Portal-side organisational hierarchy" bullet calls out the `Structure.code` round-trip semantics and the deferred-to-ADR-0028 items (`Pole`, `Service`, arbitrary nesting, per-source enrichment, full cascade sync). - No code changes, so no `pnpm ci:check` impact. `pnpm exec prettier --check` clean on the four touched files. ## Test plan - [x] `pnpm exec prettier --check` — clean on the four touched files. - [x] Internal links resolve (ADR-0026 ↔ ADR-0027 mutual references, plus the `ADR-0028` dangling marker left intentional for the future sync ADR). - [ ] Review focus — the two new Architecture bullets phrasing; the ADR-0025 bullet's small scope-literal touch-up; CLAUDE.md roll-up wording. ## What's next Now unblocked — per ADR-0026 §"Phasing" and ADR-0027 §"Phasing": 1. ADR-0027 Implementation PR 1 — `Region` / `Delegation` / `Structure` Prisma schema + inline reference-data migration (Région Nouvelle-Aquitaine + Délégation 33 + a handful of test-tenant structures) + `Structure.kind` catalogue + drift-gate extension. Independent of (2) at the schema level. 2. ADR-0026 Implementation PR 1 — `Person` / `User` / `UserScope` Prisma schema + `PersonAndUserProvisioner` called from `SessionEstablisher` + `Person.source` catalogue + drift-gate extension + updated `PrincipalBuilder` populating `Principal.user.{id, personId}` from the real rows. Can ship in parallel with (1). 3. ADR-0026 Implementation PR 2 — `PrismaScopeResolver` replacing `StubScopeResolver` + `/admin/users/:id/scopes` admin-app screen + `prisma/seed.ts` populating the 19 test personas' `user_scopes` per `notes/test-tenant-role-assignments.md`. Depends on both (1) and (2). 4. ADR-0028 (proposed) — Pléiades + Acteurs+ + cascade syncs + facet schemas (Salarié / Élu / Adhérent / Bénévole / Bénéficiaire / PartenaireExterne) + operator-confirmed Person-reconciliation flow + the deferred org-hierarchy extensions (`Pole`, `Service`, per-source enrichment). --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #219	2026-05-24 16:58:39 +02:00
julien	30cefc4488	docs(adr): split ADR-0026 + propose ADR-0027 (Structure hierarchy) (#217 ) CI / check (push) Successful in 2m53s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m42s Details CI / a11y (push) Successful in 1m51s Details CI / perf (push) Successful in 3m22s Details Docs site / build (push) Successful in 2m31s Details ## Summary Splits [ADR-0026](docs/decisions/0026-person-user-portal-data-model.md) into two sibling ADRs after a cascade / acteurs_plus source-of-truth audit caught a design break: the first draft pinned `Etablissement.finess` as primary key, but ≥ 30 % of APF's real structure inventory has no FINESS (antennes, dispositifs, entreprises adaptées, mouvement, administratif, siège). \| ADR \| Status \| Scope \| \| --- \| --- \| --- \| \| [ADR-0026](docs/decisions/0026-person-user-portal-data-model.md) — narrowed \| `proposed` \| `Person` + `User` + `UserScope` only (identity model) \| \| [ADR-0027](docs/decisions/0027-portal-side-organisational-hierarchy.md) — new \| `proposed` \| `Region` + `Delegation` + `Structure` (cascade-aligned: `kind` discriminator + nullable FINESS / SIRET / `codePaie`) \| \| `ADR-0028` (future) \| — \| Pléiades + Acteurs+ + cascade syncs + facet schemas (renumbered from the old `ADR-0027` placeholder) \| No code changes — all three artefacts moving in this PR are markdown. ## What lands \| File \| Change \| \| --- \| --- \| \| `docs/decisions/0026-person-user-portal-data-model.md` \| Title trimmed (drop `+ organisational hierarchy`); `Region` / `Delegation` / `Etablissement` schema removed; `Person.email` unique constraint dropped (two distinct humans can share an email — see Lifecycle); Lifecycle rewritten without email-based dedup; `UserScope.value` documented as opaque string referencing ADR-0027 codes; Confirmation drops `Etablissement.kind` bullet; ADR-0027 sync references renumbered to ADR-0028; "What ADR-0026 ships vs adjacent ADRs" rewritten to three columns. \| \| `docs/decisions/0027-portal-side-organisational-hierarchy.md` \| New. Decision = Option B (`Structure` with `kind` discriminator + nullable FINESS / SIRET / `codePaie`, internal `code` PK that doubles as FINESS for medico-social structures). Considered options A (FINESS-only — original ADR-0026 draft), B (chosen), C (full cascade replication), D (remote read against cascade). Inline-migration seed for the test tenant (Region 75 + Delegation 33 + a handful of medico-social structures + `siege`); full inventory deferred to ADR-0028's cascade sync. `Structure.kind` enum-as-string drift-gated. \| \| `docs/decisions/README.md` \| ADR-0026 row: title updated, status stays `proposed`. New ADR-0027 row: `proposed`, tags `data, backend`. \| \| `CLAUDE.md` \| Roll-up clarifies: `0001 → 0025 accepted`; `ADR-0026 + ADR-0027 proposed`. `@RequireScope` Prisma-resolver roadmap entry references both ADRs + the ADR-0028 follow-up. No new Architecture bullet (entries land when their ADRs ship). \| ## Why split The cascade audit was the trigger. Cascade — APF's medico-social structure registry + Pléiades/Talentia HR integration — models `Structure` with a seven-value type discriminator: `medico_social`, `antenne`, `dispositif`, `entreprise_adaptee`, `mouvement`, `administratif`, `sanitaire`. Three of those (`antenne`, `dispositif`, part of `entreprise_adaptee`) do not have a FINESS by construction. Cascade carries FINESS / SIRET / SIREN / Pléiades `codePaie` / Talentia `codeCompta` on separate per-source enrichment rows (`StructureSourceFiness`, `StructureSourceSirene`, `StructureSourcePleiades`, `StructureSourceTalentia`), nullable and many-to-one against `Structure`. The acteurs_plus audit confirmed: acteurs_plus does not store FINESS / SIRET / SIREN on its hierarchy entities at all — it uses a portal-internal `code` (unique string) + an `externalId` pointer. The first ADR-0026 draft's `Etablissement.finess` PK excluded all non-medico-social structures by construction. The fix is not to make FINESS nullable on `Etablissement` (that smuggles the discriminator into absence-of-value semantics) — it is to adopt cascade's `Structure` + `kind` discriminator directly. Doing that inside ADR-0026 would have ballooned its scope; splitting is the cleaner shape: - ADR-0026 keeps a tight focus on identity (`Person` + `User` + `UserScope`). The Person model is unchanged from the first draft except for the email-dedup rewrite (already discussed before the audit landed). - ADR-0027 owns the org hierarchy with the cascade-aligned schema, the seeding posture, and the deferred parts (`Pole`, `Service`, arbitrary nesting, per-source enrichment) called out explicitly as ADR-0028's territory. ## ADR-0027 schema highlights ```prisma model Structure { // Portal-internal stable code. For medico-social structures we set // code = FINESS (round-trips through scope literals + URLs cleanly). // For non-medico-social structures: APF-internal slug ('siege', // 'apf-bdx-merignac', 'ea-toulouse', 'mvt-national', …). code String @id name String // Aligned with cascade's Structure.type discriminator. Drift-gated. kind String // 'medico_social' \| 'antenne' \| 'dispositif' // \| 'entreprise_adaptee' \| 'mouvement' // \| 'administratif' \| 'siege' finess String? @unique // 9 digits, NULL for non-medico-social siret String? @unique // 14 chars, NULL when not SIRENE-registered codePaie String? @unique // Pléiades 6-char, NULL in v1 delegationCode String? // NULL for siège, mouvement national delegation Delegation? @relation(fields: [delegationCode], references: [code]) @@index([kind]) @@index([delegationCode]) } ``` The vocabulary mismatch — ADR-0025's scope kind name is `etablissement` but the value is now a `Structure.code` of any kind — is documented as a known wart, with a possible ADR-0025 amendment as the rename path if a maintainer trips over it. ## Notes for the reviewer - `Person.email` unique constraint dropped. Two distinct humans genuinely can share an email (shared family alias, generic `info@` mailbox, error in an upstream feed). The first draft had `email String? @unique` carried over from a "let's use it as a v1 dedup key" line of thinking that the audit reshaped. The lifecycle now treats `entraOid` as the only natural key the v1 provisioner trusts; email is an attribute, indexed for operator-driven lookup (admin UI search, ADR-0028 reconciliation flow), not a constraint. - `UserScope.value` has no FK to ADR-0027 tables. Deliberate: a scope can outlive its target (a structure decommissioned mid-quarter still has historical UserScope rows pointing at its code, which the audit log needs to read). Admin UI write path validates; runtime guard tolerates stale codes (they fail the resource match, not the sign-in). - The old open PR `docs/adr-0026-accept-and-tighten-lifecycle` is superseded by this one. That branch promoted ADR-0026 (full first draft) to `accepted`. The Q1 / Q2 resolutions from that PR are preserved here — Q1 (no email-dedup) is the new ADR-0026 Lifecycle section; Q2 (inline-migration seed) moves to ADR-0027's "Seeding posture" section since it is org-hierarchy-specific. The old PR can be closed without merging. - No code changes, so no `pnpm ci:check` impact. `pnpm exec prettier --check` clean on the four touched files. ## Test plan - [x] `pnpm exec prettier --check` — clean on the four touched files. - [x] ADR cross-references resolve (every `ADR-NNNN` link in the two ADRs round-trips; the new ADR-0028 reference is a known dangling marker for the future sync ADR). - [ ] Review focus — cascade / acteurs_plus audit findings as cited in ADR-0027 §"Context"; the schema choices in ADR-0027 (kind enum, nullable FINESS/SIRET, internal `code` PK); the `Person.email` non-unique change in ADR-0026; the scope-kind vocabulary mismatch documented in ADR-0027. ## What's next (post-merge) Per ADR-0026 §"Phasing" and ADR-0027 §"Phasing" — the two ADR PRs ship in parallel once accepted: 1. ADR-0027 Implementation PR 1 — `Region` / `Delegation` / `Structure` Prisma schema + inline reference-data migration + `Structure.kind` catalogue + drift-gate extension. 2. ADR-0026 Implementation PR 1 — `Person` / `User` / `UserScope` Prisma schema + `PersonAndUserProvisioner` called from `SessionEstablisher` + `Person.source` catalogue + drift-gate extension + updated `PrincipalBuilder`. Independent of (1) at the schema level — can ship in parallel. 3. ADR-0026 Implementation PR 2 — `PrismaScopeResolver` replacing `StubScopeResolver` + `/admin/users/:id/scopes` admin screen + `prisma/seed.ts` populating the 19 test personas' `user_scopes` per `notes/test-tenant-role-assignments.md`. Depends on both (1) and (2) — the seed references `Structure.code` values from (1) and writes `UserScope` rows from (2). 4. ADR-0028 (proposed) — Pléiades + Acteurs+ + cascade syncs + facet schemas (Salarié / Élu / Adhérent / Bénévole / Bénéficiaire / PartenaireExterne) + operator-confirmed Person-reconciliation flow + schema extensions (`Pole`, `Service`, per-source enrichment) the sync needs. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #217	2026-05-24 06:55:43 +02:00
julien	8266e5b172	docs(adr-0026): person + user portal-side data model (proposed) (#213 ) CI / check (push) Successful in 2m43s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m36s Details CI / a11y (push) Successful in 3m4s Details CI / perf (push) Successful in 4m54s Details Docs site / build (push) Successful in 4m50s Details ## Summary [ADR-0025](docs/decisions/0025-authorization-model-privileges-roles-scopes.md) shipped the authorization model with three stubs explicitly deferred to a follow-up ADR: - `Principal.user.id` and `Principal.user.personId` carry the Entra `oid` as a placeholder — `apps/portal-bff/src/auth/principal-builder.ts` documents the seam. - `StubScopeResolver` returns `[{ kind: 'unrestricted' }]` for every signed-in user; the per-persona scope values documented in `notes/test-tenant-role-assignments.md` have nowhere to live. - `@RequireScope`'s `ScopableResource` shape references an `Etablissement` / `Delegation` / `Region` chain that has no Prisma table. ADR-0026 specifies the portal-side data model that closes those stubs. Decision-only, status `proposed` — implementation lands in two PRs once accepted. ## What lands \| File \| Change \| \| --- \| --- \| \| `docs/decisions/0026-person-user-portal-data-model.md` \| New ADR. MADR 4.0.0 format. Tags: `data`, `backend`, `security`. ~310 lines. \| \| `docs/decisions/README.md` \| One new index row for 0026 (status `proposed`, 2026-05-24). \| ## ADR scope The ADR commits the schema for: - `Person` golden record — stable identity, can exist without a portal account (Pléiades pre-provisioning, dossier bénéficiaires, alumni). `source` field tracks provenance (`self-signin` in v1; `pleiades` / `acteurs-plus` join the catalogue with ADR-0027). - `User` portal-account overlay — one-to-zero-or-one with Person, lazy-created on first OIDC callback. Portal-only state (`lastSignInAt`, future a11y preferences) rides here, not on the shared Person row. - `UserScope` — confirms the migration whose shape ADR-0025 §"Sources of truth — apf_portal-side `user_scopes` table" already specified. - `Region` / `Delegation` / `Etablissement` — organisational hierarchy with externally-meaningful codes (INSEE / French dept / FINESS) as primary keys, matching the on-the-wire shape of the scope literals (`etablissement:0330800013`, `delegation:33`). The ADR explicitly defers: - Facet schemas (`Salarie`, `Adherent`, `Benevole`, `Elu`, `Beneficiaire`, `PartenaireExterne`) — they track upstream-system shape and ride alongside their producing sync. - Pléiades / Acteurs+ sync logic, reconciliation policy between sync-owned and admin-UI-owned fields. Both deferrals point at ADR-0027 (Pléiades + Acteurs+ syncs + facet schemas) as the next-up ADR. ## Notes for the reviewer - Why `Person` + `User` split and not a single table. The "Considered Options" section walks through this. Option A (User-only) breaks down the moment a dossier holder who never signs in needs a stable identifier. Option D (Person with embedded facet columns) forces every Pléiades or Acteurs+ schema change through a table that both shapes share, which is exactly the kind of coupling that ADR-0027 needs the freedom to design out. - Why externally-meaningful primary keys for the hierarchy. `Region.code` / `Delegation.code` / `Etablissement.finess` are INSEE / FINESS codes — stable across reorgs and already on every URL the portal will mint. Adding a separate UUID would force every consumer to indirect through it for no gain. The trade-off (no in-place rename — if a délégation merges, delete + re-insert with the new code) is bounded by how rarely INSEE rebases. - Lazy User creation at first sign-in. v1 has no Pléiades data; the OIDC callback creates the Person + User pair the first time it sees a new `oid`. When Pléiades sync ships (ADR-0027), the same provisioner extends with a `Person.externalId` lookup before falling back to `email`. The schema does not change between the two regimes — only the provisioner's lookup order does. - `Person.source` and `Etablissement.kind` as enum-as-string + drift-gate extension. The catalogue-drift gate ([ADR-0025 §"Confirmation"](docs/decisions/0025-authorization-model-privileges-roles-scopes.md) and `scripts/check-catalogue-drift.mjs`) was built precisely to constrain hand-edited string columns. Extending it to assert every `Person.source` write is in the closed catalogue closes one of the soft spots in the v1 schema without standing up a Postgres ENUM. - PII posture. `Person.firstName` / `lastName` / `email` are flagged in the ADR's Decision Drivers. The Pino redact list ([ADR-0012](docs/decisions/0012-observability-pino-opentelemetry.md)) and the audit-log salt ([ADR-0013](docs/decisions/0013-audit-trail-separated-postgres-append-only.md)) already cover Entra `oid`; the new PII fields ride the same posture (caller-redacted at the audit module, redacted at the Pino logger before the line ships). - What "two PRs" means in the More Information section. PR 1: Prisma schema migration + `PersonAndUserProvisioner` called from `SessionEstablisher` + drift-gate extension. PR 2: `PrismaScopeResolver` replacing `StubScopeResolver` + `/admin/users/:id/scopes` screen + `prisma/seed.ts` populating the 19 test-tenant personas' `user_scopes` rows. - Backward compatibility for in-flight Redis sessions. Sessions minted before the schema migration carry a Principal whose `user.id` is the Entra `oid` placeholder. The legacy-session bridge in [`apps/portal-bff/src/auth/principal-extractor.ts`](apps/portal-bff/src/auth/principal-extractor.ts) (added in #208) already handles this — when the migration deploys, those sessions continue to work for the 12 h absolute-TTL window, after which every session in Redis has the real `personId`. ## Open questions to resolve before acceptance These were flagged in the ADR text and are worth surfacing here for the review pass: - `Person.email` as the v1 dedup key. The ADR's "Bad, because" item — two Pléiades records sharing an email would crash the unique constraint. ADR-0027 will add the `externalId` precedence, but in the interim the v1 lazy-creator either trusts emails-are-unique (acceptable for the test tenant where every persona has a distinct one) or skips the dedup attempt and creates a fresh Person per `oid`. The ADR currently picks the dedup-by-email path; flag if the safer choice is "always fresh, reconcile later". - Should `Region` / `Delegation` / `Etablissement` migrations be seeded as part of the schema PR, or kept as a separate dataset import? The ADR is silent on this; my default is "seed the geographic codes APF actually operates in" (a one-off SQL fixture in the migration directory). Worth confirming. ## Test plan - [x] `pnpm exec prettier --check docs/decisions/0026-person-user-portal-data-model.md docs/decisions/README.md` — clean. - [ ] Review focus — the chosen Option B vs the rejected A/C/D, the deferred facets list, the `Person.source` catalogue, the `Etablissement.kind` catalogue, and the two open questions above. - [ ] Once accepted, the implementation phasing in the ADR's `§More Information` opens (2 PRs). ## What's next - This PR — ADR-0026 ships as `proposed`. - Acceptance PR — review pass, address open questions, promote `proposed → accepted` (same cadence as [#201 → #205](docs/decisions/0025-authorization-model-privileges-roles-scopes.md) for ADR-0025). - Implementation PR 1 — Prisma schema + lazy provisioner. - Implementation PR 2 — `PrismaScopeResolver` + admin-UI scope-seeding + test-tenant seed. - ADR-0027 — Pléiades + Acteurs+ syncs + facet schemas (the deferred surface from this ADR). --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #213	2026-05-24 02:19:29 +02:00
julien	c9a1e195fe	docs(adr-0025): promote to accepted + sync persona matrix with test tenant (#205 ) CI / check (push) Successful in 2m0s Details CI / commits (push) Has been skipped Details CI / scan (push) Failing after 1m54s Details CI / a11y (push) Successful in 1m44s Details CI / perf (push) Successful in 3m49s Details Docs site / build (push) Successful in 2m45s Details ## Summary ADR-0025 was merged as `proposed` in #201. The test tenant (`apfrd.onmicrosoft.com`) has since been provisioned with the full role / user matrix — 4 privileges + 24 security groups + 19 users with all assignments per the persona table. The ADR is now the implementation reference, so this PR: 1. Promotes the ADR from `proposed` to `accepted`. 2. Syncs the document with what is actually in place — the privilege catalogue grows from 1 to 4 entries (the previously "anticipated future" privileges that the test tenant already has), and the persona matrix grows from 10 to 19 entries (so every one of the 24 functional-role groups has at least one member, closing the gap that prompted `notes/test-tenant-role-assignments.md` and `notes/entra-group-members.md`). 3. Records the Entra app-role GUIDs in a new "Provisioned in the test tenant" subsection for traceability — the GUIDs are stable IDs the implementation will need. 4. Updates the index + the `CLAUDE.md` roll-up. No code changes. No implementation skeleton — that lands in the next PR (proposed: `feat(libs/feature/auth): authorization types + Principal builder skeleton`). ## What lands \| File \| Change \| \|---\|---\| \| `docs/decisions/0025-authorization-model-privileges-roles-scopes.md` \| Frontmatter `status: proposed → accepted`; privilege catalogue extended from 1 to 4 entries; persona matrix rewritten from 10 to 19 entries; new `Provisioned in the test tenant (2026-05-20)` subsection capturing the four app-role GUIDs. \| \| `docs/decisions/README.md` \| 0025 row: `proposed → accepted`. \| \| `CLAUDE.md` \| Roll-up `0001 → 0024 accepted` → `0001 → 0025 accepted`; Architecture list grows an "Authorization model" bullet. \| The two operator-facing notes files (`notes/test-tenant-role-assignments.md`, `notes/entra-group-members.md`) are gitignored and unchanged — they served their purpose during tenant provisioning and remain as runbooks. ## Notes for the reviewer - Why promote now rather than couple with the first implementation PR (the pattern from #194 → #195 → #196). The Entra-side provisioning is the implementation for this ADR — the next PR is a portal-side reflection of decisions that are already concrete in the tenant. Promoting now keeps the document honest about what the test tenant runs against. - Why all 4 privileges enter the v1 catalogue. The ADR originally shipped `Portal.Admin` as the sole v1 entry and listed the other three under "anticipated near-future entries". The test tenant has all four; the catalogue should match. The three new entries are explicitly marked "provisioned; consumer surface deferred" so a reader does not look for non-existent surfaces. - Why 19 personas, not the cleaner 24 (one per role). Several APF jobs genuinely combine multiple roles (RH siège often handles paie + compta; DPO often wears the quality officer hat; local delegates often grow out of volunteer roles). Densifying these existing personas is more faithful to real APF org structure than inventing 14 single-role test users. Distinct personas were created where the scenario is distinct (scope variations, governance positions) — see the matrix in the ADR for the breakdown. - Why `apf-role-partenaire` stays empty in v1. Placeholder per the original ADR; no consuming surface to test against. The group exists in Entra so the schema is locked, but a user assignment without a guard to exercise would be theatre. The first partner-facing feature adds the user. - GUIDs in the ADR. The four app-role GUIDs are repo-stable identifiers; recording them in the ADR keeps the document self-sufficient when a future contributor opens it without access to the Entra portal. The 24 functional-role group GUIDs are tenant-specific and stay in a gitignored `infra/test-tenant.entra.json` once the implementation PR creates it — referenced by name only in `libs/feature/auth/src/lib/entra-group-to-role.ts`. - No `prettier --write` damage. The persona matrix is a wide table; Prettier sometimes reflows wide markdown tables. The diff is clean — Prettier left the table intact on this run. ## Test plan - [x] `prettier --check docs/decisions/0025-authorization-model-privileges-roles-scopes.md` — passes (hook ran on commit). - [x] Markdown links inside the ADR still resolve (`0020`, references to other ADRs unchanged). - [x] Status row in `docs/decisions/README.md` reflects `accepted`. - [x] `CLAUDE.md` roll-up line + Architecture list updated; no other instances of "0024" needed bumping. - [ ] Review focus — the expanded privilege catalogue (4 entries, one of them already had a guard, three new ones documented), the 19-entry persona matrix, the "Provisioned in the test tenant" subsection (especially the GUIDs — make sure none was mistyped from `notes/role-user.txt`). ## What's next With ADR-0025 accepted, the implementation phasing recorded in its `§More Information` opens: 1. PR — `libs/feature/auth` extension : `authorization.types.ts` (catalogue constants for the 4 privileges + 24 functional roles + 6 scope kinds), `entra-group-to-role.ts` (slug map skeleton with placeholder GUIDs ; the operator drops real GUIDs into `infra/test-tenant.entra.json` separately), `Principal` builder hook on the OIDC callback, no new guards yet. 2. PR — `@RequireRole` + `@RequireScope` decorators + guard tests : real composition tests against the 19 personas. 3. PR — drift CI gate : ESLint custom rule asserting every `@RequireRole('...')` literal in code is in the catalogue. 4. PR — `prisma/seed.ts` for `user_scopes` : depends on the `Person` + `User` schema (proposed ADR-0026). --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #205	2026-05-23 17:42:57 +02:00
julien	ef5073de8a	docs(adr-0025): authorization model — privileges × roles × scopes (#201 ) CI / scan (push) Successful in 2m32s Details CI / commits (push) Has been skipped Details CI / check (push) Successful in 3m5s Details CI / a11y (push) Successful in 8m51s Details CI / perf (push) Successful in 10m47s Details Docs site / build (push) Successful in 10m46s Details ## Summary Proposes [ADR-0025](docs/decisions/0025-authorization-model-privileges-roles-scopes.md) — the portal's general-purpose authorization model. Status: `proposed`. No code in this PR; the goal is to lock the model and the v1 catalogues before the implementation chantier opens. The model rejects stargate's linear hierarchy (`Admin ⊃ Directeur ⊃ RH ⊃ Collaborateur`) and adopts three orthogonal axes: \| Axis \| What it carries \| Source of truth \| \|---\|---\|---\| \| Privileges \| Portal-level capabilities (`Portal.Admin`, future `Portal.Auditor`, …) \| Entra app roles, `roles` claim \| \| Functional roles \| What someone does in APF (`rh`, `directeur-etablissement`, `elu-cd-tresorier`, …) \| Entra security groups, `groups` claim → curated slug catalogue \| \| Scopes \| Where a role applies (`etablissement:0330800013`, `delegation:33`, `unrestricted`, …) \| apf_portal-side `user_scopes` table (v1) ; future Pléiades feed \| The three axes compose at sign-in into a session-resident `Principal`. The portal's guards consume the structured shape; a deterministic projector flattens it to the `roles[]` list that `apf-ai-service` expects per [ADR-0024](docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md). ## What lands - `docs/decisions/0025-authorization-model-privileges-roles-scopes.md` — full MADR with context, decision drivers, four considered options, exhaustive v1 catalogues, Entra-side configuration, `Principal` shape, AI-service projection, guard surface, ten test-tenant personas, consequences, confirmation criteria, pros/cons per option, ABAC migration path, related ADRs, and proposed follow-up ADRs. - `docs/decisions/README.md` — index row for ADR-0025 (`proposed`, tags `security, backend, data`, 2026-05-20). No `CLAUDE.md` update — ADR stays in `proposed` until reviewed; the accepted-ADRs roll-up at the top of `CLAUDE.md` stays at 0001 → 0024. Promotion to `accepted` lands in the same PR that ships the implementation skeleton (`libs/feature/auth` extension with `Principal` builder + catalogues). ## Highlights worth review focus - Privilege catalogue is intentionally minimal: only `Portal.Admin` in v1. Anticipated future entries (`Portal.Auditor`, `Portal.SecurityOfficer`, `Portal.DPO`) are mentioned in the ADR but not formalised — each one rides an amendment ADR. - Functional-role catalogue is closed-set, 22 entries grouped into workforce (15), governance (6), volunteer (2), external (1, placeholder). Adding a new slug requires an ADR amendment. The CI drift gate (proposed in §"Confirmation") asserts no orphan `@RequireRole('x')` literal in code. - Scope kinds are also closed-set: `self`, `etablissement:<finess>`, `delegation:<dept>`, `region:<insee>`, `siege`, `unrestricted`. The `value` carriers are documented (FINESS code rather than internal `etablissement.id` because FINESS is stable across reorgs). - `Principal` shape is the contract for everything downstream. Documented field-by-field. Built once at sign-in, persisted in the Redis session, refreshed on every authenticated request. - `PrincipalProjector` for the AI service is mechanical: union of privileges + roles + scope-strings, no inclusive expansion. The projector is the only seam that knows about the flat shape; the rest of the portal never touches it. - Closed-vs-open catalogue trade-off spelled out: the friction of "every new role rides an ADR amendment" is the price of "every slug in code is one a human approved". The drift CI gate enforces the discipline. - ABAC migration path documented so a future contributor does not feel they must rewrite authorization to introduce a single Cedar/OPA-shaped rule. ## Test-tenant personas The ADR proposes ten test users covering every interesting combination of the three axes. Table in §"Test-tenant personas" of the ADR; here's the summary the user can act on: \| Login \| Privileges \| Functional roles \| Scopes \| \|---\|---\|---\|---\| \| `admin@<tenant>` \| `Portal.Admin` \| `collaborateur`, `rh` \| `unrestricted` \| \| `directeur-bordeaux@<tenant>` \| — \| `directeur-etablissement`, `collaborateur` \| `etablissement:0330800013` \| \| `directeur-complexe@<tenant>` \| — \| `directeur-etablissement`, `collaborateur` \| two `etablissement:` scopes \| \| `rh-aquitaine@<tenant>` \| — \| `rh`, `collaborateur` \| `delegation:33` \| \| `rh-siege@<tenant>` \| — \| `rh`, `responsable-paie`, `collaborateur` \| `unrestricted` \| \| `collab-simple@<tenant>` \| — \| `collaborateur` \| `self` \| \| `tresorier-bordeaux@<tenant>` \| — \| `elu-cd-tresorier`, `elu-cd` \| `delegation:33` \| \| `dpo@<tenant>` \| — \| `dpo`, `collaborateur` \| `unrestricted` \| \| `it@<tenant>` \| — \| `it`, `collaborateur` \| `unrestricted` \| \| `benevole-aquitaine@<tenant>` \| — \| `benevole`, `benevole-responsable` \| `delegation:33` \| Entra test-tenant setup the user needs to provision after acceptance: 1. One app role: `Portal.Admin` (likely already there from the existing dev tenant; document the GUID in `apps/portal-bff/.env.test`). 2. 22 security groups, one per functional-role slug in the catalogue: `apf-role-collaborateur`, `apf-role-chef-equipe`, `apf-role-chef-service`, `apf-role-directeur-etablissement`, `apf-role-directeur-territorial`, `apf-role-rh`, `apf-role-responsable-paie`, `apf-role-comptable`, `apf-role-juriste`, `apf-role-dpo`, `apf-role-rssi`, `apf-role-it`, `apf-role-formation`, `apf-role-qualite`, `apf-role-communication`, `apf-role-elu-ca`, `apf-role-elu-cd`, `apf-role-elu-cd-president`, `apf-role-elu-cd-tresorier`, `apf-role-elu-cd-secretaire`, `apf-role-delegue`, `apf-role-benevole`, `apf-role-benevole-responsable`, `apf-role-partenaire`. 3. The ten test users with the membership matrix above. 4. App registration manifest tweak: `groupMembershipClaims: 'SecurityGroup'` + `optionalClaims.idToken: [{ name: 'groups' }]` so the BFF sees the memberships in the ID token. GUIDs and credentials stay in the operator's hands (out of git). When the user has provisioned the tenant, drop the GUIDs into `infra/test-tenant.entra.json` (gitignored) and the implementation PR wires `libs/feature/auth/src/lib/entra-group-to-role.ts` against them. ## Notes for the reviewer - Why not just extend stargate's `RoleMapper`.* The mapper's inclusive expansion (`Admin → [admin, directeur, rh, collaborateur]`) bakes in the wrong assumption — that roles form a chain. Reusing it would force every new role into the chain too. The three-axis model has no such forcing function. - Why `Person` is conspicuously absent here. Authorization is keyed on the portal-side `User` account (Entra OID, session). The proposed `Person` + `User` split lands in a sibling ADR (proposed: ADR-0026) because the two decisions have different audiences — auth model is a backend/security concern; golden record is a data/domain concern. They will land in coordinated PRs. - *Why FINESS rather than internal UUID for `etablissement:` scopes. FINESS codes are the canonical APF identifier for an établissement, stable across the internal-database churn (etablissement merges, reorgs, system migrations). Using the FINESS as the scope value means scope strings stay readable, debuggable, and stable when an établissement gets a new internal `id` after a Prisma migration. - Why no time-bound roles in v1.** APF does have interim assignments (acting Directeur for two months while the permanent one is on leave). The `user_scopes` table already has `expiresAt` to lay the groundwork; extending the role axis with time bounds is a future ADR amendment when a concrete use case lands. - Coordination with apf-ai-service. The PrincipalProjector spec here matches exactly what `apf-ai-service`'s RBAC matrix tests expect (each chunk's ACL is a string-match against `Principal.roles[]`). The ADR explicitly notes that the projector is the only place that knows about the flat shape — keeping the AI-side contract honoured without polluting the portal-side guards. ## Test plan - [x] `prettier --check docs/decisions/0025-authorization-model-privileges-roles-scopes.md` — passes (hook ran on commit). - [x] Markdown links inside the ADR resolve (`0008`, `0009`, `0010`, `0011`, `0013`, `0020`, `0021`, `0024`, plus the proposed ADR-0026 / ADR-0027 placeholders). - [x] Index row in `docs/decisions/README.md` follows the table's existing format. - [x] No tag-vocabulary additions required — `security`, `backend`, `data` are all in the existing vocab. - [ ] Review focus — the v1 catalogues (privileges + 22 functional roles + 6 scope kinds), the `Principal` shape, the projection contract for the AI service, and the ten test personas. Catalogue closures are deliberate; raising the lid requires an amendment so the v1 list deserves a careful pass. ## What's next (once accepted) The implementation phasing recorded in the ADR's §"More Information": 1. PR — types + Principal builder + Entra mapping skeleton. Lands `libs/feature/auth/src/lib/authorization.types.ts` (catalogue constants), `entra-group-to-role.ts` (slug map), and the OIDC callback hook that extends `req.session.user` with `privileges` / `roles` / `scopes`. No new guards yet. 2. PR — `@RequireRole` + `@RequireScope` decorators + guard tests. Stub principal in unit tests; real session in e2e. 3. PR — drift CI gate. ESLint custom rule or `pnpm run` script: every `@RequireRole('...')` / `@RequirePrivilege('...')` / scope literal must exist in the catalogue constants. 4. PR — test-tenant seed. `prisma/seed.ts` populating the ten personas' `user_scopes` rows. Depends on the `Person` + `User` schema PR landing first. In parallel, the user provisions the test tenant per the §"Test-tenant personas" instructions above. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #201	2026-05-20 18:42:45 +02:00
julien	883c5151de	feat(portal-bff): ai-bridge controller — SSE chat + JSON rag/models (#196 ) CI / commits (push) Has been skipped Details CI / scan (push) Successful in 3m20s Details CI / check (push) Successful in 4m2s Details CI / a11y (push) Successful in 1m23s Details CI / perf (push) Successful in 6m0s Details Docs site / build (push) Successful in 2m56s Details ## Summary Step 3 of the AI-relay chantier (after #194 ADR and #195 client skeleton). Wires the BFF-side live surface that the SPA's future chatbot widget will consume. [ADR-0024](docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md) is promoted from `proposed` to `accepted` in the same change. Three end-user routes under `/api/ai/`, gated by the active portal session (no `@RequireAdmin` — AI is a regular-user surface): \| Route \| Verb \| Wire \| Maps to \| \|---\|---\|---\|---\| \| `/api/ai/chat` \| `POST` \| `text/event-stream` \| `apf.ai.v1.ChatService.Chat` (server-stream) \| \| `/api/ai/rag/search` \| `GET` \| `application/json` \| `apf.ai.v1.RagService.Search` (unary) \| \| `/api/ai/models` \| `GET` \| `application/json` \| `apf.ai.v1.ModelsService.ListModels` (unary) \| CSRF and session validation are delegated to the global middleware mounted in `main.ts` (per [ADR-0009](docs/decisions/0009-auth-flow-oidc-pkce-msal-node.md) and [ADR-0021](docs/decisions/0021-phase-2-security-baseline.md)); the controller asserts `req.session.user` and emits 401 if absent. ## What lands ### `apps/portal-bff/src/grpc/ai-bridge/` ``` ai-bridge/ ├── ai-bridge.module.ts imports AiClientModule, exports the controller ├── ai-bridge.controller.ts 3 routes — POST chat (SSE), GET rag/search, GET models ├── sse.writer.ts ChatEvent oneof → SSE frame translator ├── sse.writer.spec.ts unit tests for the codec ├── ai-bridge.controller.spec.ts end-to-end against an in-process fake gRPC server └── dto/ ├── chat-request.dto.ts class-validator body shape (POST /chat) └── rag-search-query.dto.ts class-validator query shape (GET /rag/search) ``` ### SSE codec (`sse.writer.ts`) Each `ChatEvent` oneof case becomes one SSE frame with a kebab-case `event:` name and a JSON-encoded `data:` payload: ``` event: token data: {"token":"…","value":"…"} event: agent-step data: {"agent":"…","step":"…","stepId":"…"} event: tool-call data: {"callId":"…","name":"…","args":{…}} event: done data: {"stats":{"tokensIn":…,"tokensOut":…,"chunksRetrieved":…}} ``` A helper `relayErrorFrame(code, message, retriable)` synthesises a relay-side `event: error` frame that matches the AI service's own `ErrorEvent` shape — the SPA's renderer needs no second code path for relay-level failures vs upstream model errors. gRPC status codes map into the `urn:apf-ai:` namespace (`UNAVAILABLE` → `urn:apf-ai:unavailable`, `DEADLINE_EXCEEDED` → `urn:apf-ai:timeout`, `PERMISSION_DENIED` → `urn:apf-ai:permission_denied`, `RESOURCE_EXHAUSTED` → `urn:apf-ai:rate_limited`, `INVALID_ARGUMENT` → `urn:apf-ai:invalid_argument`, anything else → `urn:apf-ai:relay_error`). The terminal `done` frame closes the stream — no `[DONE]` sentinel, per ADR-0024. ### Controller (`ai-bridge.controller.ts`) - `POST /api/ai/chat` — builds an `apf.ai.v1.ChatRequest` from the validated DTO + session-derived Principal, calls `ChatClient.chat()`, drains the `ClientReadableStream<ChatEvent>` into SSE frames written on the raw Express `Response`. `req.on('close', …)` propagates browser disconnect through an `AbortController` into `call.cancel()` so the upstream LLM stops (per `apf-ai-service/docs/streaming.md`). - `GET /api/ai/rag/search` — unary RAG call. `topK` defaults to 0 (server picks the default). `source` and `documentId` query params surface the same filter fields the upstream RPC accepts. - `GET /api/ai/models` — unary lookup of the provider catalogue. The SSE writes happen on the raw Express response (manual `setHeader` + `flushHeaders` + `write` + `end`) rather than through NestJS's `@Sse()` decorator, because `@Sse()` is GET-only and the chat endpoint is POST (the SPA carries the conversation history in the body). ### Lifecycle hooks `AiClientModule` now implements `OnApplicationShutdown` and closes the four gRPC stubs (Chat / Rag / Ingestion / Models). The four stubs share the same HTTP/2 channel (gRPC-js dedups on `endpoint + credentials`), so the `close()` calls are cheap, but kept explicit so adding a fifth stub later is an obvious one-line addition. `main.ts` now calls `app.enableShutdownHooks()` so `SIGTERM` / `SIGINT` / `SIGHUP` actually route through the lifecycle interface. ### DTOs `ChatRequestDto` constrains: - `messages` — 1 to 64 entries; each has `role ∈ {user, assistant, system}` (no `tool` — tool messages are constructed BFF-side per ADR-0024 §"Tool-dispatch contract") and `content` ≤ 16 KB. - `conversationId`, `model`, `provider` — optional, ≤ 64 / 128 chars. `RagSearchQueryDto`: - `query` — required, non-empty. - `topK` — optional, integer in `[1, 50]` (the AI service has its own cap; the BFF rejects out-of-range values early). - `source` / `documentId` — optional pass-through filters. ### Documentation - ADR-0024 frontmatter: `status: proposed` → `accepted`. - `docs/decisions/README.md` index reflects the new status. - `CLAUDE.md` Architecture section grows an "AI service relay" bullet; the roll-up line moves from "ADRs 0001 → 0023" to "0001 → 0024"; the shipped-on-main list grows an "AI relay surface" entry. - `apps/portal-bff/.env.example` documents `AI_SERVICE_GRPC_ENDPOINT` / `AI_SERVICE_CLIENT_ID` / `AI_SERVICE_GRPC_TLS` and points operators at `apf-ai-service`'s own docker-compose for the runtime dependency. ## Notes for the reviewer - No live AI service in this PR's local-dev stack. `apf-ai-service` runs from its own repo (`/home/jgautier/Works/apf-ai-service`) with its own `infra/docker-compose.yml`. The BFF dials `localhost:8080` by default — the host-published port of the AI service's container. This is option (a) from ADR-0024 §"Open question — Compose orchestration": two independent stacks, dial across via host networking. Merging the compose files into one would couple two release cadences without operational payoff. - Tests run against an in-process fake `grpc.Server`. All five spec cases on the controller wire it up against a fake `ChatService` + `RagService` + `ModelsService` server bound to `127.0.0.1:0` (random port). No mocks — the controller's gRPC client makes a real connection, real serialisation, real cancellation propagation. Cost: ~0.5 s overhead from the gRPC server setup. - CSRF + session middleware are unchanged. The new POST endpoint is protected by the existing double-submit CSRF middleware mounted in `main.ts` (per [ADR-0021](docs/decisions/0021-phase-2-security-baseline.md)). The SPA's fetch call needs to send the `X-CSRF-Token` header matching the `__Host-portal_csrf` cookie — same protocol as every other POST in the BFF. No per-controller wiring required. - Manual session check rather than a guard. Three reasons: (1) matches the existing pattern in `me.controller.ts`; (2) the session check is the only authorization gate (no roles to evaluate) — a guard would add ceremony without payoff; (3) the SSE controller already takes control of the response object (`@Res()`), which `UseGuards` interacts with awkwardly. Throwing `UnauthorizedException` lets `StructuredErrorFilter` produce the 401 envelope before any header is flushed. - Why the controller does NOT use `@Sse()`. NestJS's `@Sse()` decorator is GET-only and emits frames from `Observable<MessageEvent>`. The chat endpoint is POST (the SPA sends conversation history in the body) and the source is a Node `Readable` stream from `@grpc/grpc-js`. Manual response handling is simpler than adapting to / from `Observable` for a single consumer. - Cancellation contract. When the SPA aborts the fetch, the browser closes the TCP connection, Express emits `'close'` on the request, the controller's `AbortController.abort()` triggers, `ChatClient` calls `.cancel()` on the gRPC stream, the AI service's `ServerCallContext.CancellationToken` cancels the upstream LLM. The spec covers the `'close'` → server-side `cancelled` event end-to-end. - No ingestion route in the BFF. Per ADR-0024 §"Out of scope", v1 admin ingestion uses the `apf-ai-service/tools/Apf.Ai.Ingest/` CLI. A future PR adds the BFF endpoint when the admin "manage AI corpus" surface ships. `IngestionClient` remains in `AiClientModule` so that future PR is one new file, not a new module plus a new client. - No bundle-size or perf surprise. The BFF is a Node process, not a SPA chunk — bundle budgets don't apply. The gRPC channel is opened lazily on first call; idle BFFs incur no upstream TCP cost. ## Test plan - [x] `pnpm nx test portal-bff` — 461 specs pass (was 443; +13 new: 8 SSE writer cases + 5 controller end-to-end cases against the in-process fake server). Worker-exit-leak warning persists from the gRPC server's slow shutdown — pre-existing pattern from PR #195; harmless. - [x] `pnpm nx lint portal-bff` — 6 pre-existing warnings, no new ones from the diff. - [x] `pnpm nx build portal-bff` — clean webpack compile. - [x] Module wiring: `AppModule` imports `AiBridgeModule`, which imports `AiClientModule`. Resolves cleanly through DI; the audit-side `HashUserIdService` is satisfied by `AiClientModule`'s local provider (per the rationale recorded in PR #195's `AiClientModule` docstring). - [ ] Manual smoke — bring up `apf-ai-service` from its own repo (`cd ../apf-ai-service && docker compose -f infra/docker-compose.yml up`), set `AI_SERVICE_GRPC_ENDPOINT=localhost:8080` in `apps/portal-bff/.env`, run `pnpm nx serve portal-bff`. Sign in to `portal-shell`, then in a terminal: ```bash curl --cookie-jar /tmp/portal-session http://localhost:3000/api/auth/login # follow Entra… curl -N \ -H 'Content-Type: application/json' \ -H 'X-CSRF-Token: <copied from cookie>' \ --cookie /tmp/portal-session \ -d '{"messages":[{"role":"user","content":"hello"}]}' \ http://localhost:3000/api/ai/chat ``` Expect a streamed SSE response terminated by an `event: done` frame. Verify `GET /api/ai/rag/search?query=test` returns a JSON response. Verify `GET /api/ai/models` lists the configured providers. ## What's next 1. PR (frontend chantier) — chatbot widget on `portal-shell` consuming the SSE endpoint. Will use `fetch` + `ReadableStream` parsing (not native `EventSource`, since POST is needed). Drag / fullscreen / suggestion UX carries forward from the stargate POC's `ChatbotWidget.tsx`. 2. PR (post-v1) — proto-drift CI gate that diffs `proto/apf-ai/` against an upstream tag of `apf-ai-service`. 3. Coordinated amendment — when the first production deployment is in scope, both repos record the same prod-hardening choice (signed `Principal` envelope vs mTLS) on the same date. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #196	2026-05-19 22:39:35 +02:00
julien	3f3f47317b	docs(adr-0024): ai service relay — gRPC dial + SSE bridge + POC principal (#194 ) CI / check (push) Successful in 2m31s Details CI / scan (push) Successful in 2m12s Details CI / commits (push) Has been skipped Details CI / a11y (push) Successful in 2m27s Details CI / perf (push) Successful in 3m59s Details Docs site / build (push) Successful in 3m56s Details ## Summary Proposes [ADR-0024](docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md) — the integration contract between `apf_portal`'s BFF and the sibling `apf-ai-service` repository. The ADR bundles four tightly-coupled sub-choices: the wire transport between BFF and AI service, the wire transport between BFF and SPA for chat streaming, how the protos reach the BFF, and how user identity travels across the boundary in v1. Status: `proposed`. No code lands in this PR — the goal is to lock the contract before the implementation chantier starts. The chosen design: \| Boundary \| Choice \| \|---\|---\| \| BFF ↔ AI service \| Native gRPC HTTP/2 via `@grpc/grpc-js`, h2c in dev / h2 + TLS in prod \| \| BFF ↔ SPA (chat) \| `text/event-stream` — one SSE frame per `ChatEvent` oneof case \| \| BFF ↔ SPA (unary) \| Plain JSON endpoints for `RagService.Search` + `ModelsService.ListModels` \| \| Proto distribution \| Vendored into `apps/portal-bff/src/grpc/proto/apf-ai/`, `ts-proto` codegen on demand, both `.proto` + generated `.ts` committed \| \| Identity (POC) \| Unsigned `Principal { subject, roles[], attributes{} }` in the proto body — mirrors `apf-ai-service`'s ADR-0010 \| \| Production hardening \| Choice between signed envelope and mTLS — explicitly deferred until first production deployment is in scope \| ## What lands - `docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md` — new MADR-formatted ADR with the four sub-choices, decision drivers, considered options, consequences, confirmation criteria, open production-hardening question, and the related-ADRs map. - `docs/decisions/README.md` — one new index row for ADR-0024 (`proposed`, tags `backend, security, observability`, 2026-05-19). No source-code changes. No `CLAUDE.md` update — the ADR stays in `proposed` until reviewed, so the accepted-ADRs roll-up at the top of `CLAUDE.md` stays at 0001 → 0023. Promotion to `accepted` lands in the same PR that ships the first implementation chantier (proto vendor + `AiClientModule`), at which point `CLAUDE.md` gets the "0024 accepted" line. ## Notes for the reviewer - Why bundle four sub-choices in one ADR rather than four. They couple tightly: the SPA-facing transport choice depends on the BFF-facing transport choice (gRPC-Web from the browser would dissolve the bridge layer entirely); the auth posture depends on having identity travel in the proto body (vendoring a different contract would change that); the proto-distribution choice depends on the contract being stable enough to vendor (a churning OpenAPI spec would push toward an SDK package). Splitting would force cross-ADR coordination on every revision. The ADR keeps a separate "Sub-choice" section per topic so each one stays reviewable on its own. - Out of scope deliberately. The chatbot UI lives in a future frontend chantier; the role mapper (Entra groups → inclusive-expanded `roles[]`) is a separate proposed ADR; the ingestion-through-BFF path waits for the admin app's "manage AI corpus" surface; tool dispatch is wired but exercised against an empty registry in v1. - Hash-salt coordination is the one operational gotcha. The same `HashUserIdService` salt has to land in both repos' deployment config so `apf-ai-service.audit_log.actor_id_hash` and `apf_portal.audit.events.actor_id_hash` produce identical values. Recorded as an open item in the ADR's "More Information" section; the deployment doc that distributes the secret is a v1-launch deliverable. - `apf-ai-service` cross-reference. The ADR references `apf-ai-service/docs/adr/ADR-0010` (POC unsigned principal) and `apf-ai-service/docs/adr/ADR-0011` (mono-transport gRPC) as upstream anchors. Both are already accepted on the AI side. The "production hardening" decision will be a coordinated amendment in both repos on the same date. - No `DownstreamApiClient` (ADR-0014) reuse. The OBO pattern in ADR-0014 targets Entra-protected downstreams that validate the user's access token. `apf-ai-service` is not Entra-protected — it accepts an unsigned Principal proto. The ADR explicitly calls this out so the reader does not expect symmetry with the Entra-protected downstream path. - Phasing recorded in the ADR's "More Information" section. This PR is step (1) "ADR accepted". Steps 2–5 are separate PRs in order: client skeleton → bridge controller → frontend chatbot → proto-drift CI gate. ## Test plan - [x] `pnpm run --silent prettier --check docs/decisions/0024-ai-service-relay-grpc-sse-bridge.md` — passes (hook ran on commit). - [x] Markdown links inside the ADR resolve to existing files (`0005`, `0009`, `0010`, `0012`, `0013`, `0014`, `0017`, plus `CLAUDE.md`). - [x] Index row in `docs/decisions/README.md` follows the table's existing format (column count, tag vocabulary, date format). - [x] No tag-vocabulary additions required — `backend`, `security`, `observability` are all in the existing vocab. - [ ] Review focus — the four sub-choices and the production-hardening deferral. Code chantier is gated on this PR's acceptance. ## What's next (once accepted) 1. PR — proto vendor + codegen + `AiClientModule` skeleton — vendors the protos, wires `ts-proto` codegen, sets up the NestJS module with the metadata interceptor and the Principal mapper, all tested against an in-process fake gRPC server. No live endpoint yet. 2. PR — `ai-bridge` controller — `POST /api/ai/chat` (SSE), `GET /api/ai/rag/search`, `GET /api/ai/models`, live against `apf-ai-service` in the dev Compose stack. 3. PR (frontend chantier) — the chatbot widget on `portal-shell` consuming the SSE endpoint. 4. PR (post-v1) — proto-drift CI gate that diffs the vendored copy against the upstream tag. 5. Coordinated amendment — when the first production deployment is in scope, both repos record the same prod-hardening choice (signed envelope or mTLS) on the same date. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #194	2026-05-19 20:11:15 +02:00
julien	7ee7b2dadf	docs(adr-0023): charts and dashboards — d3 + observable plot (#170 ) CI / check (push) Successful in 1m17s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m2s Details CI / a11y (push) Successful in 2m33s Details CI / perf (push) Successful in 6m7s Details Docs site / build (push) Successful in 3m37s Details ## Summary Records the decision to use D3 + Observable Plot, wrapped in a new `libs/shared/charts/`, as the chart toolkit shared by `portal-shell` and `portal-admin`. ADR-only — implementation lands as the next chantier(s). This is staged as a 3-PR chantier per the agreed plan: \| PR \| Périmètre \| \| --- \| --- \| \| PR 1 (this one) \| ADR-0023 — decision + a11y contract + bundle plan. \| \| PR 2 \| `libs/shared/charts/` foundations + 3 starter components (`<lib-bar-chart>`, `<lib-donut-chart>`, `<lib-stacked-bar-chart>`). \| \| PR 3 \| Integration on the `/audit` page — daily-volume bar + outcome-breakdown donut + event-type-over-time stacked bar. \| ## What lands ### [`docs/decisions/0023-charts-d3-observable-plot.md`](docs/decisions/0023-charts-d3-observable-plot.md) Full MADR 4.0.0 record. Highlights: - Choice: D3 + Observable Plot, both from Mike Bostock / Observable Inc., both MIT, both past 1.0. Plot covers ~80 % of standard charts in declarative one-liners; D3 stays the escape hatch for bespoke viz (heatmap, sankey, …) inside the same lib. - Why not D3 alone: ~250 LOC per chart × 4-5 types × a11y discipline = sustained code investment before the first dashboard ships. - Why not ECharts / Chart.js: 600 KB minified + canvas-rendered + an `aria` plugin afterthought (ECharts), or narrower vocabulary + brittle dark-mode (Chart.js). Both furthest from the Angular-Signals-zoneless idiom the rest of the workspace runs on. - A11y contract is baked into `_internal/` (palette, tabular fallback, SVG `<title>` / `<desc>` builders) so every chart inherits WCAG 2.2 AA + AAA-targeted compliance from the lib, not from contributor discipline. Six commitments, each unit-tested per chart component. - Bundle plan: ~65 KB gzip added to a chart-bearing lazy chunk (d3 modules tree-shaken + Plot + thin wrapper) — well under [ADR-0017](docs/decisions/0017-performance-budgets-lighthouse-ci.md)'s 100 KB cap. - Component contract: every `<lib--chart>` exposes the same Signal-based input shape (`[data]`, `[caption]`, `[description]`, `[ariaLabel]`, `[colorScheme]`) regardless of whether Plot or raw D3 powers the rendering. ### [`docs/decisions/README.md`](docs/decisions/README.md) ADR-0023 added to the index table. ### [`CLAUDE.md`](CLAUDE.md) - "Architecture (recorded in ADRs)" gains a "Charts + dashboards" bullet describing the lib + a11y baseline + bundle posture. - "Repository status" bumps the ADR range to `0001 → 0023`. - "Still on the roadmap" gains the charts implementation entry pointing at this ADR. ## Notes for the reviewer - Why honour the user's D3 preference rather than recommend pure ECharts?* D3 (and by extension Plot) is the closest match to the project's tech bar ("stable, recognized, battle-tested") for data-viz on the web; it's also the user's stated preference, and Plot's higher-level layer eliminates the "250 LOC per chart" cost that would otherwise push us toward an alternative. The ADR explicitly walks through ECharts + Chart.js as runners-up so future challengers see the trade-offs we chose against. - Why a single shared lib rather than per-app charts? Both SPAs (portal-shell + portal-admin) will host dashboards. The chart vocabulary, a11y contract, palette, and theme integration are identical between the two — duplicating into app-local code would invite drift. The lib stays at `libs/shared/charts/` next to `libs/shared/ui/`. - Why the `_internal/` folder for cross-cutting code? Single source of truth for the colour palette and the a11y plumbing. A lint rule (added in PR 2) will ban consumers from importing `d3-scale-chromatic` directly so the colour-blind-safe palette stays the only path. - Why no ADR amendment to ADR-0016 / ADR-0017? Both are binding constraints, not superseded. The new ADR operationalises both for the chart surface; cross-references in the "Related ADRs" section make that explicit. ## Test plan - [x] ADR validates as MADR 4.0.0 (frontmatter, section order, tag vocabulary). - [x] No code touched — lint / test / build matrix unaffected. - [x] `docs/decisions/README.md` index updated in the same change per the [ADR conventions](docs/decisions/README.md#conventions). - [ ] Review for trade-off accuracy: are the bundle estimates fair? Is the "Plot covers ~80 % of standard charts" framing defensible against the user's mental model of D3? - [ ] Implementation chantier (PR 2) lands directly behind this if accepted: `pnpm add -w d3 @observablehq/plot @types/d3`, `libs/shared/charts/` scaffold via `pnpm nx g @nx/angular:library --name=shared-charts --directory=libs/shared/charts --standalone=true --unitTestRunner=vitest-analog --tags="scope:shared,type:shared" --no-interactive`, then the 3 starter components. ## What's next If accepted as-is, PR 2 (lib foundations + 3 starter components) follows. If a reviewer wants to push back on D3-vs-ECharts or on the a11y contract's strictness, this is the right PR to surface that — no implementation has started. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #170	2026-05-16 21:28:03 +02:00
julien	aa8ad97feb	fix(portal-admin): adr refs point at gitea, not the madr template repo (#153 ) CI / check (push) Successful in 1m47s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 1m48s Details CI / a11y (push) Successful in 2m1s Details CI / perf (push) Successful in 3m33s Details ## Summary Records the decision to render `docs/*/.md` as a separately-deployed static site using VitePress + `vitepress-plugin-mermaid`. This is ADR-only — the implementation (install + `.vitepress/config.ts` + `docs/index.md` + Gitea Actions workflow) lands as the next chantier. Splitting them keeps the decision review focused on the why before the how. ## What lands ### [`docs/decisions/0022-docs-site-vitepress.md`](docs/decisions/0022-docs-site-vitepress.md) Full MADR 4.0.0 ADR. Decision drivers, 4 considered options (VitePress, MkDocs Material, Docusaurus 3, Astro Starlight), site-structure mapping, Mermaid integration, deployment + CI plan, consequences, revisit triggers. Tags: `process`, `infrastructure`. Key choices captured: - VitePress wins on toolchain alignment (Vite already in the workspace via `@nx/vite`, `vite-plugin-angular`, Vitest). MkDocs Material was the strong runner-up; the Python runtime tax in Gitea Actions tipped the balance. - `vitepress-plugin-mermaid` for ```` ```mermaid ```` blocks ([ADR-0009](docs/decisions/0009-auth-flow-oidc-pkce-msal-node.md) sequence + [architecture.md](docs/architecture.md) C4 are hard requirements). - Site sources entirely from `docs/`. Mapping: - `docs/index.md` (new, Hero layout) → `/` - `docs/development.md` → `/development` - `docs/architecture.md` → `/architecture` - `docs/decisions/README.md` → `/decisions/` (curated index, kept as section landing) - `docs/decisions/00NN-….md` → auto-listed in the sidebar by numeric prefix - `docs/setup/0N-….md` → `/setup/0N-…` - Excluded via `srcExclude`: `docs/README.md` (stays as the git-side / IDE-preview index — option A from the prior discussion) and `docs/decisions/template.md` (authoring scaffold). - Empty placeholder sections in `docs/README.md` (Operations runbooks, Security/perf/a11y rationales) are NOT pre-created as empty pages — they appear in the sidebar when real content lands. - Deployment: dedicated hostname (provisional `docs.portal.apf.fr`) behind the same Caddy reverse-proxy as the apps, fed by a new `.gitea/workflows/docs-site.yml` triggered on `docs/` push. Exact hostname follows the future infrastructure ADR; not locked here. ### [`docs/decisions/README.md`](docs/decisions/README.md) ADR-0022 added to the index table. ### [`CLAUDE.md`](CLAUDE.md) Bumps the ADR range from `0001 → 0021` to `0001 → 0022`. New bullet in the "Architecture (recorded in ADRs)" section describing the docs-site choice in one paragraph. Implementation tracked in "Still on the roadmap" until the next PR lands it. ## Notes for the reviewer - Why ADR before implementation? The choice between VitePress / MkDocs Material / Docusaurus / Astro Starlight is exactly the "stable + recognized + innovative" trade-off [CLAUDE.md](CLAUDE.md) asks to document. Reviewing the rationale on its own (without dragging through the install diff) keeps the discussion focused. - Why not surface ADRs inside `portal-admin`? Audience mismatch — [ADR-0020](docs/decisions/0020-portal-admin-app.md) §"Audience is disjoint" frames `portal-admin` around APF internal operators (CMS, audit, user directory), not architects. The full reasoning is in ADR-0022 §"Context and Problem Statement". - Why two index artefacts (`docs/README.md` + future `docs/index.md`)? Option A from the structure discussion. Each serves a distinct audience: `README.md` is the flat link list that renders well in IDEs / Gitea source view; `index.md` will be the VitePress Hero landing for the web audience. Light duplication, no maintenance pressure (the IDE one only needs updating when sections appear/disappear). - Why `vitepress-plugin-mermaid` rather than Docusaurus's built-in Mermaid? The community plugin is a sub-1.0 dependency on the wrapper (Mermaid itself is mature), but Mermaid is so mainstream that switching it out is a half-day rewrite if the plugin stalls. Trading that risk against Docusaurus's MDX-by-default footprint + React runtime is a net win. - Why `process` + `infrastructure` tags?** Mirrors [ADR-0015](docs/decisions/0015-cicd-gitea-actions.md) (also a CI / deploy decision with content authoring implications) and is consistent with the [tag vocabulary](docs/decisions/README.md#tag-vocabulary). No new tag invented. ## Test plan - [x] `docs/decisions/0022-docs-site-vitepress.md` validates as MADR 4.0.0 (frontmatter, section order). Index in [`docs/decisions/README.md`](docs/decisions/README.md) updated in the same PR per [ADR conventions](docs/decisions/README.md#conventions). - [x] No code touched — `lint / test / build` matrix unaffected. - [ ] Review for trade-off accuracy: did I get MkDocs Material's strengths right? Is Astro Starlight's maturity argument fair? - [ ] Implementation chantier (next PR): `pnpm add -D vitepress vitepress-plugin-mermaid mermaid`, `docs/.vitepress/config.ts`, `docs/index.md`, `.gitea/workflows/docs-site.yml`, `package.json` scripts. Will land within the same week assuming this ADR holds. ## What's next If accepted as-is, the immediate follow-up is: 1. Install VitePress + the Mermaid plugin. 2. Author `docs/.vitepress/config.ts` with the sidebar shape spelled out in this ADR (auto-generated sub-sidebar for `/decisions`, hand-curated top-level). 3. Author `docs/index.md` (Hero layout). 4. Add the `docs-site` Gitea Actions workflow. 5. Wire the dev script (`pnpm docs:dev`) into `package.json` so contributors can preview locally. If reviewers want to push back on the toolchain choice (MkDocs Material in particular has a strong case for the theme polish), this is the right PR to surface that — implementation hasn't started. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #153	2026-05-15 18:48:07 +02:00
julien	da2bd6d481	docs(adr-0021): phase-2 security baseline (helmet, CORS, CSRF, rate-limit, error envelope) (#124 ) CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m12s Details CI / check (push) Successful in 2m22s Details CI / a11y (push) Successful in 49s Details CI / perf (push) Successful in 3m48s Details ## Summary Documents the security middleware stack shipped across the five most recent BFF PRs (#115, #117, #120, #122, #123) as a single MADR ADR. Today the rationale for each choice lives in code comments and PR descriptions; the next contributor reaching for `csurf`, a cookie-only CSRF, or a hardcoded localhost CORS fallback won't have a single place to read why those are wrong here. ADR-0021 covers: - Response envelope — `{ error: { code, message, traceId } }`, single contract shared between Nest's `StructuredErrorFilter` and raw Express middlewares (CSRF, rate-limit) via the exported `errorResponse()` helper. Status code → code mapping documented. 500s never leak the underlying exception. - CSRF — session-bound double-submit, not pure cookie-vs-header. Rationale: a subdomain-takeover cookie injection can't bypass the comparison because the source of truth is the server-side session token, not the cookie. Cookie is the SPA's read-only mirror. - CORS allowlist — `CORS_ALLOWED_ORIGINS` mandatory at boot, no fallback. "Works in dev, breaks in prod" is the exact trap the validator catches. - Rate limiting — buckets keyed by session id (auth) or IP (anonymous), 10/min on `/auth/login` + `/auth/callback`, 120/min general, `/api/health` skipped. In-memory v1 store; Redis-backed migration is one constructor arg. - Helmet config — defaults plus three overrides (HSTS prod-only, `crossOriginResourcePolicy: cross-origin`, CSP prod-only). Each override has a code-anchored justification. ## Scope This is the implementation-level security ADR. The strategic security baseline ADR — OWASP ASVS reference level, HDS / GDPR / NIS 2 framing, RSSI sign-off — remains paused per the note in [CLAUDE.md](CLAUDE.md). When that ADR lands it'll either confirm 0021 or supersede pieces of it; 0021 is explicit about which choices are tactical and revisitable. ## Notable structural choices in the ADR - "Considered Options" mirrors the actual debate. For CSRF: session-bound vs pure double-submit vs `csurf` vs synchronizer. For rate-limit bucket key: sessionID-then-IP vs IP-only vs Entra `oid`. Each rejected option has its "Bad, because …" so the reader sees why we didn't go that way. - Each "Decision Outcome" line points at the file / function that enforces it. Cross-references are absolute paths so they survive folder reorgs. - The "Consequences" section is brutally honest about trade-offs. In-memory rate-limit doesn't scale horizontally. The CSRF cookie is XSS-readable. No `details` field in the envelope for field-level validation errors yet. These aren't hidden in the prose. ## Other doc touches - [docs/decisions/README.md](docs/decisions/README.md) index entry added. - [notes/handoff.md](notes/handoff.md) refreshed (gitignored; not part of the commit but useful for the next session). ## Noted for a separate PR (out of scope here) [CLAUDE.md](CLAUDE.md) §"Repository status" still says "The Nx workspace is not yet bootstrapped" and refs ADRs up to 0020. The whole paragraph is stale (the project is fully scaffolded, 22 ADRs in place). Worth a small dedicated docs PR. ## Test plan - [x] `pnpm exec prettier --check docs/decisions/` → clean. - [x] ADR follows the MADR 4.0.0 template (frontmatter with `status`, `date`, `decision-makers`, `tags`; sections in the canonical order). - [x] Tags drawn from the vocabulary in [docs/decisions/README.md](docs/decisions/README.md#tag-vocabulary): `security`, `backend`. - [x] Index in `docs/decisions/README.md` updated in the same change. - [x] Cross-references to ADRs 0009, 0010, 0012, 0015 verified. - [ ] Renders in Gitea / IDE markdown preview without parser warnings. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #124	2026-05-13 23:54:45 +02:00
julien	c5e91f240b	docs(decisions): add ADR-0019 i18n + ADR-0020 portal-admin (#89 ) CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m22s Details CI / check (push) Successful in 2m36s Details CI / a11y (push) Successful in 53s Details CI / perf (push) Successful in 3m25s Details ## Summary Pure documentation PR. Two ADRs that answer the two strategic questions raised after the footer chantier: - [ADR-0019](docs/decisions/0019-internationalisation-angular-localize.md) — how the portal handles multiple languages. - [ADR-0020](docs/decisions/0020-portal-admin-app.md) — where portal administration lives. Implementation will land across follow-up feature PRs, each consumable on its own. ## ADR-0019 — Internationalisation Decision: `@angular/localize` in build-time mode, two locales (`fr` default served at `/`, `en` source). Path-based URLs always prefixed (`/fr/...`, `/en/...`); `/` smart-redirects via cookie → `Accept-Language` → `fr`. The locale switcher in the footer writes a `__Host-portal_locale` cookie and hard-refreshes to the matching bundle. Considered and rejected: - `@angular/localize` runtime mode (single bundle, higher LCP / payload cost). - `@ngx-translate` / `transloco` (community libraries; tech-bar prefers Angular first-party for foundational primitives). - Query-param URL strategy (fragile, weaker SEO, `<html lang>` becomes harder). - Subdomain URL strategy (breaks `__Host-` cookie scoping from ADR-0010). Scope boundary: UI strings owned by developers (templates + `$localize` in code). Editorial content (CMS-managed pages, news, etc.) is BFF-served already localised — that's the admin-app pipeline (ADR-0020), not `@angular/localize`. First sweep consequence: the duplicate `/accessibility` + `/accessibilite` routes collapse to one Angular route with locale-translated paths. ## ADR-0020 — `portal-admin` Decision: new Angular SPA `portal-admin` alongside `portal-shell`, sharing the existing `portal-bff` via `/api/admin/` routes guarded by an Entra `admin` role plus `@RequireMfa({ freshness: 600 })` at the entry route. Distinct origin + cookie + session (`__Host-portal_admin_session`). v1 modules* (all four selected): 1. Editorial pages CMS (multilingual content, fed back to `portal-shell` via the BFF). 2. Sidebar menu management (activates the `requiredPermissions` field already on `MenuItem`). 3. User list (read-only). 4. Audit log viewer (consumes the `audit.events` table per ADR-0013, via the `audit_reader` role). Out of v1: B2B invitations (stay in Entra Admin Center), feature flags (no substrate yet), CMS workflow / approval flows, theme customisation, live preview. Considered and rejected: - `/admin/` lazy-loaded inside `portal-shell` (admin code in the same origin → weaker defense in depth, admin URL not IP-restrictable independently). - Two SPAs and* two BFFs (doubles infra at our scale — bricolage). - Off-the-shelf admin tooling (Retool, etc. — escapes our security baseline). Performance budget for admin: ≤ 500 KB gzip initial (vs 300 KB for `portal-shell`, per ADR-0017). Lighthouse Performance ≥ 85 on critical admin routes (vs ≥ 90 on `portal-shell`). Same a11y baseline (ADR-0016), same dark-mode support. Shared-libs graduation: `Icon`, `LayoutStateService`, brand tokens, dark-mode SCSS helpers move from `portal-shell` to `libs/shared/{ui,state}` when both apps need them. Mechanical refactor; tracked as the first implementation PR. ## Implementation roadmap (out of scope of this PR) ADR-0019: 1. Install `@angular/localize`, wire build target. 2. Mark every existing UI string in `portal-shell` with `i18n` + `@@id`; produce `messages.fr.xlf`. 3. Locale switcher in footer + `/api/preferences/locale` BFF route + smart redirect at `/`. 4. Collapse the duplicate accessibility routes into a localised single route, with 301s. 5. CI gate: `nx build portal-shell --localize` is added to `ci:check` and fails on missing translation. ADR-0020: 1. `nx g @nx/angular:app portal-admin` skeleton. 2. Shared-libs extraction (`libs/shared/ui`, `libs/shared/state`). 3. BFF `AdminModule` + `AdminRoleGuard` + smoke `GET /api/admin/me`. 4. Admin shell (header / sidebar / footer with an "Admin" badge). 5. One PR per v1 module — suggested order: CMS pages → menu management → audit viewer → user list. ## Test plan - [x] Both ADRs follow MADR 4.0.0 (frontmatter, sections, tags from the canonical vocabulary). - [x] `docs/decisions/README.md` index updated in the same commit. - [x] `CLAUDE.md` architecture summary picks up entries for both decisions and bumps the ADR coverage line to 0020. - [ ] Read-through review — invite the project lead to push back on any decision before locking implementation. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #89	2026-05-11 12:29:54 +02:00
julien	4476cbb518	docs(decisions): add ADR-0018 — environment configuration strategy (#80 ) CI / check (push) Successful in 1m36s Details CI / commits (push) Has been skipped Details CI / scan (push) Successful in 2m2s Details CI / a11y (push) Successful in 1m36s Details CI / perf (push) Successful in 3m33s Details ## Summary Records the per-environment config strategy for both apps. ADR-only — no code changes; the implementation is anchored in §Confirmation against the next feature work that touches per-environment values. ## What lands [ADR-0018 — Environment configuration](docs/decisions/0018-environment-configuration-strategy.md): - SPA: Angular `environment.ts` + project.json `fileReplacements`. Build-time substitution; no runtime config fetch (rejected for the LCP/TTFB cost it would add and the deploy-time HTML rewrite that the alternatives need). Concretely cleans up the hard-coded URLs we left in `observability/tracing.ts` and `home-status.service.ts` ("hard-coded for v1 — env-config when it lands" comments). - BFF: keep `process.env` + small per-key boot-time validators (the shape `apps/portal-bff/src/config/check-database-url.ts` already follows). `@nestjs/config` rejected as too heavy for the current key count; `zod` not justified yet. - Audit log connection: formalises the `AUDIT_DATABASE_URL` split that ADR-0013 §"Wired as features land" already pointed at. When set, the `AuditModule` instantiates a second Prisma client with `audit_writer`-only credentials (defense in depth); when unset, the dev fallback (shared pool + `SET LOCAL ROLE audit_writer` per transaction) keeps working. A boot-time `UPDATE`-rejection self-test runs against the dedicated pool when configured — refuses to start if the pool can mutate the audit table. The §Confirmation block cross-references the env-var-as-boot-gate items already pre-figured in ADR-0009 / ADR-0010 / ADR-0012 / ADR-0013 / ADR-0014, so the validator pattern is the single landing place when those features ship. ## What does NOT change in this PR - No `apps/portal-shell/src/environments/*.ts` files yet — landed alongside the next feature that actually needs per-environment values. - No `AUDIT_DATABASE_URL` validator in BFF — same; lands when the second pool is wired. - No CLAUDE.md restructuring; just one extra bullet under the Architecture summary referencing ADR-0018. ## Doc updates - `docs/decisions/README.md` index — new row for ADR-0018. - `CLAUDE.md` Architecture summary — one-line reference to ADR-0018 between the perf-budget and local-quality-gates entries. ## Test plan - [ ] CI green on this PR (`format:check`). - [ ] ADR-0018 renders in the doc index with the right tags (`frontend`, `backend`, `infrastructure`, `process`) and 2026-05-10 date. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #80	2026-05-10 04:58:02 +02:00
Julien Gautier	0e58e32d29	chore: relocate ADRs from decisions/ to docs/decisions/ to consolidate documentation Move the ADR folder under docs/ alongside the rest of the project documentation. Convention (flat folder, globally-sequential 4-digit numbering, tags-based categorization, MADR 4.0.0 format) is unchanged - only the path moved. - git mv decisions docs/decisions preserves history for all 18 ADRs + README + template (19 files renamed in this commit). - ADR-0001 amended in-place with a dated note documenting the relocation. Status remains 'accepted' - the location detail changed, the decision did not. - All cross-references updated: - CLAUDE.md (~17 ADR links + 3 mentions of decisions/ in the Project rules section) - docs/README.md (now references decisions/ as a sibling under docs/) - docs/setup/03-angular-nx-monorepo.md (paths shortened from ../../decisions/ to ../decisions/, since setup/ and decisions/ are now both inside docs/) - docs/decisions/0003 ../CLAUDE.md adjusted to ../../CLAUDE.md (one extra level of nesting) - docs/decisions/template.md mention of the README path - notes/asvs-level-decision-briefing-rssi.md mention of the index Sanity verified: every ADR link in CLAUDE.md, docs/setup/03, and docs/decisions/0001 resolves to an existing file. pnpm nx run-many -t lint passes on 8 projects.	2026-04-30 18:57:59 +02:00

15 Commits