Phase 2 of ADR-0012 — closes the loop SPA → BFF → DB. With this
PR a single user action (page load, click, form submit) produces
one trace whose root span is owned by the SPA and whose child
spans cover the BFF request, Postgres queries, and (eventually)
Redis / downstream-API hops.
Runtime libs added (production deps):
- @opentelemetry/sdk-trace-web browser tracer + provider
- @opentelemetry/exporter-trace-otlp-http OTLP/HTTP+JSON exporter
- @opentelemetry/instrumentation auto-instrumentation runtime
- @opentelemetry/instrumentation-fetch fetch + W3C traceparent propagation
- @opentelemetry/instrumentation-document-load initial-paint timings
- @opentelemetry/instrumentation-user-interaction click / keypress / submit
Code:
- apps/portal-shell/src/observability/tracing.ts — WebTracerProvider
bootstrap. Documents the load-order constraint inline (must be
the very first import of main.ts, same pattern as the BFF). No
context-zone package because the workspace is zoneless (per
ADR-0004); the default StackContextManager covers the
auto-instrumentation cases.
- main.ts now imports the tracing module as line 1.
CORS plumbing for end-to-end propagation:
- BFF (apps/portal-bff/src/main.ts) calls enableCors with a
minimal dev allowlist (http://localhost:4200) and explicit
permission for the W3C traceparent and tracestate headers. The
full security-grade CORS belongs to phase-2 security ADR; this
is the strict minimum for the SPA→BFF link to keep the trace
context across origins.
- OTel Collector (infra/local/otel-collector.yaml) gains a cors
block on its OTLP/HTTP receiver so the browser's OTLP POST
clears its own pre-flight.
ADR-0012 §Confirmation: a new "Wired in the SPA foundation PR
(phase 2)" block enumerates what landed here; the carry-over
"Wired as features land" list is updated to drop the SPA-side
SDK item that used to live there and to add a CORS-grade
follow-up note.
Verified locally:
- pnpm exec nx run-many -t lint test build → 8 projects green.
- pnpm audit clean.
- After ./infra/local/dev.sh up observability and nx serve
portal-shell, opening http://localhost:4200 produces a
document_load trace in Jaeger with the SPA service.name; a
manual fetch from DevTools to /api/health on the BFF produces
a child span on the same trace.
Wire Tailwind CSS 4 in the portal-shell app per ADR-0016 (the future
host of spartan-ng components in libs/shared/ui will read from the
Tailwind tokens via the shared-tokens lib).
- pnpm add -D tailwindcss @tailwindcss/postcss postcss
- apps/portal-shell/postcss.config.js declares @tailwindcss/postcss
- apps/portal-shell/src/styles.scss renamed to styles.css and now
contains a single @import 'tailwindcss' directive. Plain CSS for the
global file avoids the Sass @import deprecation warning that fires
when Tailwind directives sit inside SCSS. Component-level styles can
still use SCSS.
- apps/portal-shell/project.json styles entry updated accordingly.
Side fix: align libs/shared/tokens and libs/shared/util tsconfigs from
module: commonjs to module: esnext. The Nx @nx/js:library --bundler=
tsc generator emits commonjs by default, but tsconfig.base.json
specifies moduleResolution: bundler, which TS only allows alongside
esnext or es2015+ modules. Without the alignment, those libs failed to
build (TS5095). All apps and libs now build green.
spartan-ng wiring is intentionally NOT in this commit. spartan-ng is
currently at 0.0.1-alpha.681 - clearly pre-1.0, which trips the
project rule against pre-1.0 dependencies. ADR-0016 chose spartan-ng
with the copy-paste mitigation, but the alpha state warrants an
explicit go/no-go decision before committing the workspace to it.
The Angular 21 unit-test builder (@angular/build:unit-test) defaults
to watch mode. Without an explicit option, 'pnpm nx test portal-shell'
hangs on 'Waiting for task' indefinitely - unsuitable for CI and
surprising for ad-hoc invocations.
Pin watch=false as the default in the target options. Add a 'watch'
configuration so developers who want continuous test running can opt
in with 'pnpm nx test portal-shell --configuration=watch'. portal-bff
uses Jest which defaults to no-watch and needs no change.
Add the @nx/angular, @nx/nest, @nx/vite, @nx/eslint plugins, then
generate the two apps. Adjust the empty-template tsconfig.base.json
to be Angular-compatible (drop project references and customConditions
that the empty-template defaults to but Angular doesn't support; keep
the strict-TS extensions from ADR-0004).
apps/portal-shell (Angular 21):
- standalone APIs, routing, SCSS, esbuild
- vitest-angular as unitTestRunner, playwright for e2e
- strict mode
- tags scope:portal-shell, type:app
- app.config.ts wired with provideZonelessChangeDetection() per
ADR-0004 (Angular 21 + Nx 22 generates without zone.js by default)
apps/portal-bff (NestJS 11):
- Express adapter (default per ADR-0005)
- Jest as unitTestRunner
- tags scope:portal-bff, type:app
- main.ts wired with a global ValidationPipe configured
whitelist + forbidNonWhitelisted + transform per ADR-0005
- Phase-2 security additions (helmet, CORS, sessions, CSRF, rate
limit, auth guards, error filter) deferred to their respective
ADRs - placeholder comment in main.ts
Workspace dependencies: class-validator + class-transformer added
(required by NestJS ValidationPipe at runtime). Nx-generated
.gitignore additions (.angular, __screenshots__) merged into ours.
.vscode/extensions.json and launch.json added by Nx are kept (do not
override our existing settings.json).
Julien Gautier