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

fix(portal-admin): adr refs point at gitea, not the madr template repo #152

Merged
julien merged 1 commits from fix/portal-admin-adr-links into main 2026-05-15 18:47:15 +02:00
Conversation 0 Commits 1 Files Changed 2
+14 -6
julien commented 2026-05-15 18:15:22 +02:00
Owner
Copy Link
Copy Source

Summary

Two ADR references in portal-admin page intros (/audit, /users) linked to https://github.com/adr/madr — the MADR template repository, not our ADRs. Copy-paste artefact from the original authoring of those pages.

Both anchors now resolve to the actual ADR file on Gitea, so a reviewer who clicks lands on the right document.

Page Anchor Was Now
audit.html ADR-0013 github.com/adr/madr Gitea 0013-audit-trail-…
users.html ADR-0020 github.com/adr/madr Gitea 0020-portal-admin-app

Why no in-app ADR viewer

A natural follow-up question — "could we render the ADRs inside portal-admin?" — was considered and rejected for v1:

  • Audience mismatch. ADR-0020 §"Audience is disjoint" frames portal-admin around APF internal staff doing CMS / audit / user-directory work. ADRs are dev / architecture artefacts mentioning Prisma, Redis, MSAL Node, OBO trade-offs — content that doesn't help an operator and blurs the line between "ops tool" and "internal tech doc".
  • Architecture cost. A live viewer would require a Markdown-rendering pipeline on the SPA, BFF↔filesystem coupling (or a build-time embedding that breaks the auto-update intent), inter-ADR link rewriting, and English-only fallback in an otherwise i18n-capable app.
  • Better alternative exists. If discoverability of docs/**/*.md becomes a real need, a separate static-site (MkDocs Material / Docusaurus / VitePress) deployed on docs.portal.apf.fr with a CI hook on docs/ changes is the battle-tested path. That's the chantier slot — a separate ADR + setup, not bolt-on inside portal-admin.

Test plan

  • pnpm nx run-many -t lint test build --projects=portal-admin — clean, 50 specs pass, lazy chunks unchanged.
  • Visual smoke: open /audit and /users in portal-admin, click the inline ADR badge, confirm the Gitea ADR page loads in a new tab.
## Summary Two ADR references in `portal-admin` page intros (`/audit`, `/users`) linked to `https://github.com/adr/madr` — the **MADR template repository**, not our ADRs. Copy-paste artefact from the original authoring of those pages. Both anchors now resolve to the actual ADR file on Gitea, so a reviewer who clicks lands on the right document. | Page | Anchor | Was | Now | | --- | --- | --- | --- | | [audit.html](apps/portal-admin/src/app/pages/audit/audit.html) | ADR-0013 | `github.com/adr/madr` | [Gitea `0013-audit-trail-…`](https://git.unespace.com/julien/apf_portal/src/branch/main/docs/decisions/0013-audit-trail-separated-postgres-append-only.md) | | [users.html](apps/portal-admin/src/app/pages/users/users.html) | ADR-0020 | `github.com/adr/madr` | [Gitea `0020-portal-admin-app`](https://git.unespace.com/julien/apf_portal/src/branch/main/docs/decisions/0020-portal-admin-app.md) | ## Why no in-app ADR viewer A natural follow-up question — "could we render the ADRs inside portal-admin?" — was considered and **rejected** for v1: - **Audience mismatch.** ADR-0020 §"Audience is disjoint" frames portal-admin around APF internal staff doing CMS / audit / user-directory work. ADRs are dev / architecture artefacts mentioning Prisma, Redis, MSAL Node, OBO trade-offs — content that doesn't help an operator and blurs the line between "ops tool" and "internal tech doc". - **Architecture cost.** A live viewer would require a Markdown-rendering pipeline on the SPA, BFF↔filesystem coupling (or a build-time embedding that breaks the auto-update intent), inter-ADR link rewriting, and English-only fallback in an otherwise i18n-capable app. - **Better alternative exists.** If discoverability of `docs/**/*.md` becomes a real need, a separate static-site (MkDocs Material / Docusaurus / VitePress) deployed on `docs.portal.apf.fr` with a CI hook on `docs/` changes is the battle-tested path. That's the chantier slot — a separate ADR + setup, not bolt-on inside portal-admin. ## Test plan - [x] `pnpm nx run-many -t lint test build --projects=portal-admin` — clean, 50 specs pass, lazy chunks unchanged. - [ ] Visual smoke: open `/audit` and `/users` in portal-admin, click the inline ADR badge, confirm the Gitea ADR page loads in a new tab.
julien added 1 commit 2026-05-15 18:15:22 +02:00
fix(portal-admin): adr refs point at gitea, not the madr template repo
CI / commits (pull_request) Successful in 2m49s
Details
CI / scan (pull_request) Successful in 2m49s
Details
CI / check (pull_request) Successful in 3m0s
Details
CI / a11y (pull_request) Successful in 1m21s
Details
CI / perf (pull_request) Successful in 2m43s
Details
e1805f596d 
`audit.html` and `users.html` cited ADR-0013 / ADR-0020 with anchors
pointing at `https://github.com/adr/madr` — that's the MADR _template_
repository, not our ADRs. Copy-paste artifact from the original
authoring.

Both links now resolve to the actual ADR file on Gitea
(`https://git.unespace.com/julien/apf_portal/src/branch/main/docs/decisions/…`)
so a reviewer who clicks lands on the right document. Surfacing the
ADRs inside portal-admin is intentionally out of scope — the audience
(APF internal admins, not architects) doesn't justify the
markdown-rendering + BFF-filesystem coupling cost; a separate static-
site for docs is a better fit and lands as its own chantier.
julien merged commit 035ea7c748 into main 2026-05-15 18:47:15 +02:00
julien deleted branch fix/portal-admin-adr-links 2026-05-15 18:47:15 +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#152
Delete Branch "fix/portal-admin-adr-links"

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?