Julien Gautier
6065922520
ADR-0012 phase 1 + phase 2 are wired (BFF + SPA), so the "Observability dev-loop" placeholder in the roadmap table now has real content to point at. Promote it from §9 (was §8) future-work list to a full §5 walkthrough sitting between "Daily commands" and "Dependency updates". What §5 covers: - Bringing up the observability stack (`./infra/local/dev.sh up observability`) with the endpoint table. - Reading a trace in Jaeger — service-dropdown filter, span attribute keys to look at, the trace-id-as-pivot pattern. - Correlating a trace with the BFF Pino logs via `trace_id` and `request_id` (the latter the per-request UUID nestjs-cls provides). - Reading SPA spans from the browser (DevTools Network + Jaeger UI cross-check). - Common gotchas — observability profile not active, CORS pre-flight on `/v1/traces`, `propagateTraceHeaderCorsUrls` mismatches, NODE_ENV mis-set, EADDRINUSE. - Pointer at the "wired as features land" deltas (CLS keys for session/user/audience, redact list, custom domain spans, prod backend) so a contributor knows what's intentionally not yet there. Renumber the rest of the doc accordingly (5→6 / 6→7 / 7→8 / 8→9) and drop the now-implemented "Observability dev-loop" line from the §9 roadmap table. `docs/README.md` cross-link updated to mention the new section.
37 lines
1.7 KiB
Markdown
37 lines
1.7 KiB
Markdown
# Documentation index
|
|
|
|
This is the entry point to all project documentation. It is maintained automatically: any addition, rename, or removal of a `.md` file under `docs/` must be reflected here in the same change.
|
|
|
|
## Conventions
|
|
|
|
- Documentation is written in **English**.
|
|
- One topic per file. Group related files into a folder when there are three or more.
|
|
- Cross-reference with relative links so they keep working in GitHub, IDEs, and exported sites.
|
|
- For architectural decisions, do **not** add them here — they belong in [decisions/](decisions/) as MADR 4.0.0 ADRs.
|
|
|
|
## Sections
|
|
|
|
### Daily development
|
|
|
|
- [development.md](development.md) — repo layout, prerequisites, initial setup, daily commands, observability dev-loop (Jaeger UI, log ↔ trace correlation), dependency updates (Renovate), conventional commit cycle. Day-to-day reference for working on the project.
|
|
|
|
### Architecture
|
|
|
|
- [architecture.md](architecture.md) — cross-cutting Mermaid diagrams: C4 system context, C4 containers, Nx module boundaries, CI/CD pipeline. Single-decision diagrams (auth sequence, ERD, etc.) live inline in their ADR.
|
|
|
|
### Onboarding & environment
|
|
|
|
Setup guides for new contributors:
|
|
|
|
- [setup/01-wsl-terminal-setup.md](setup/01-wsl-terminal-setup.md) — modern WSL terminal (Zsh + Powerlevel10k + CLI tools)
|
|
- [setup/02-dev-web-stack.md](setup/02-dev-web-stack.md) — Node via nvm, pnpm via corepack, Docker
|
|
- [setup/03-angular-nx-monorepo.md](setup/03-angular-nx-monorepo.md) — Angular + Nx monorepo bootstrap
|
|
|
|
### Operations & runbooks
|
|
|
|
_Empty — to be populated when we deploy._
|
|
|
|
### Security, performance, accessibility
|
|
|
|
_Empty — placeholders to be filled with rationale docs alongside their corresponding ADRs._
|