docs(development): refresh after phase-3a + add topology / trace diagrams #160
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: julien/apf_portal#160
Reference in New Issue
Block a user
Delete Branch "docs/refresh-development-guide"
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?
Summary
docs/development.mddrifted asportal-adminshipped, the docs site landed, Prisma stayed pinned at 6.x, and a fair chunk of the phase-2 "to come" roadmap quietly turned into "shipped". Surgical refresh of the affected sections + two Mermaid diagrams where prose alone wasn't carrying the cognitive load.What changed
Section 1 — Repo layout
apps/portal-admin/+apps/portal-admin-e2e/added (both exist onmainsince #134, were never reflected in the tree).prisma.config.tsremoved (phantom — Prisma 6.x doesn't ship one). The "Prisma 7" tag corrected to "Prisma 6.x" with the ADR-0006 pin reference.docs/index.md,docs/architecture.md,docs/.vitepress/added.docs-site.yml,renovate.yml.Section 3 — Initial setup, new diagram
Mermaid
flowchartof the local-dev topology. Host-side dev servers (portal-shell:4200,portal-admin:4300,portal-bff:3000,docs:5173) ↔ Compose containers (Postgres, Redis, OTel) ↔ viewer profiles (Jaeger, pgweb). Replaces a ports/services context that was scattered across §3 and §5.Section 4 — Daily commands
portal-adminadded to serve / test / generate examples.--testFile(we hit this empirically while debugging the sidebar spec for #151). The new wording recommends positional path for Vitest,--testPathPattern=…for Jest.docs:dev,docs:build,docs:preview), plus the recipe for adding an ADR.Section 5 — Observability, new diagram
Mermaid
sequenceDiagramshowing how a click becomes a trace: browseruser_interactionspan →traceparentheader → BFF span → Pino log line with matchingtrace_id→ OTLP batch → Jaeger UI. Anchors the prose's "trace_id is the correlation point" rule with a visual.Section 6 — Renovate
New subsection "Transitive vulnerabilities —
pnpm.overrides". Documents the pattern from #159 so the next contributor hitting a transitive vuln (Renovate silent, dashboard empty) has the playbook on hand without re-discovering it.Section 9 — Sections to come
Restructured into two groups:
main; only the prose is missing. Each entry now cites the PR(s) that landed the implementation.Notes for the reviewer
pnpm docs:devadds nothing to the prereqs list — just Node + pnpm, both already required). Leaving the table as is.Test plan
rm -rf docs/.vitepress/{cache,dist} && pnpm docs:build— clean, 6.3 s.docs/.vitepress/dist/development.html— both new diagrams produceclass="mermaid"markers.grep -c 'class="mermaid"\|<svg' development.html→ 2.pnpm docs:dev, navigate to/development, confirm both diagrams render (topology with port labels readable, sequence diagram with the trace flow). Toggle dark mode, confirm diagrams flip theme.auth ≈ ADR-0009 series,admin ≈ #127, #128, #134, #136, #140–142,downstream ≈ #137–139,OpenAPI ≈ #143,capabilities ≈ #151).What's next
The two largest "doc to write" entries (Auth dev-loop, Audit-log inspection workflow) are good candidates for the next docs chantier — both have shipped code, RSSI-relevant content, and would benefit from a guided walkthrough. Not blocking anything; pick when the team has bandwidth.
The development guide drifted as portal-admin shipped, the docs site landed, and Prisma stayed pinned at 6.x. Surgical pass. Section 1 (Repo layout): * Add `apps/portal-admin/` and `apps/portal-admin-e2e/` — both exist on `main` since #134. * Drop the phantom `prisma.config.ts` (Prisma 6.x doesn't ship one) and fix the "Prisma 7" tag to "Prisma 6.x" with the ADR-0006 pin reference. * Add `docs/index.md`, `docs/architecture.md`, `docs/.vitepress/` + new workflows (`docs-site.yml`, `renovate.yml`) so the layout matches what `ls` actually shows. Section 3 (Initial setup) — new diagram: * Mermaid `flowchart` of the local-dev topology (host-side dev servers + Compose containers + viewer profiles + the optional docs site). Replaces the prose ports-table that was scattered across §3 and §5 for new contributors. Section 4 (Daily commands): * Add `portal-admin` to serve / test / generate examples. * Correct the single-test-file recipe — Nx's vitest executor rejects `--testFile`; use positional `path/to/file.spec.ts` for Vitest projects, `--testPathPattern=…` for Jest. * New "Documentation site" subsection — `docs:dev` / `docs:build` / `docs:preview`, link to ADR-0022. Section 5 (Observability): * Mermaid `sequenceDiagram` of how a click becomes a trace (browser span → traceparent → BFF span → Pino log line with matching trace_id → OTLP batch → Jaeger). Anchors the correlation rule that the prose explained but didn't visualise. Section 6 (Renovate): * Add "Transitive vulnerabilities — `pnpm.overrides`" subsection. Documents the pattern from #159 (vite + esbuild via VitePress) so the next contributor hitting a transitive vuln has the playbook on hand. Section 9 (Sections to come): * Split into "Code shipped — doc to write" and "Not yet". Many phase-2 items moved out of "to come" since the code has shipped (auth, sessions, MFA decorator, admin module, audit viewer, user directory, downstream strategies, OpenAPI tooling, capabilities endpoint). The roadmap now reflects what's actually still missing.