feat(spa): proxy /api in dev-server, relative bffApiBaseUrl

Make the SPAs reach the BFF same-origin via the Angular dev-server's
proxy, so the dockerised dev mode (ADR-0030) works when the SPA is
accessed from a remote browser (e.g. http://<vm-ip>:4200/) — and CORS
is bypassed in dev altogether.

- New proxy.conf.js per SPA: /api -> ${BFF_TARGET:-http://localhost:3000}
  (JS form so the env var can swap the target at startup without a
  rebuild).
- project.json serve.options.proxyConfig wired in for both apps.
- environment.ts (shell + admin) bffApiBaseUrl: 'http://localhost:3000/api'
  -> '/api'. Production siblings can still set an absolute origin if
  the SPA and BFF live on different hosts; tracing.ts resolves either
  form against window.location.origin.
- tracing.ts: new URL(env, window.location.origin) — relative bases no
  longer throw, absolute bases keep their own origin.
- dev.compose.yml: BFF_TARGET=http://portal-bff:3000 on portal-shell
  and portal-admin so the proxy hits the BFF container by Compose DNS.
  Native nx serve leaves it unset and falls back to localhost.

OTel exporter URL and cross-SPA links remain absolute — same remote-
browser issue, but not blocking the 'Backend unreachable' path this
PR targets. Out of scope here, follow-up if needed.

Stacked on top of feat/dockerised-dev-mode.

apps/portal-admin/project.json

@@ -84,7 +84,8 @@
       "continuous": true,
       "executor": "@angular/build:dev-server",
       "options": {
-        "port": 4300
+        "port": 4300,
+        "proxyConfig": "apps/portal-admin/proxy.conf.js"
       },
       "configurations": {
         "production": {

apps/portal-admin/proxy.conf.js

@@ -0,0 +1,21 @@
+// Angular dev-server proxy for portal-admin.
+//
+// Mirrors apps/portal-shell/proxy.conf.js — same rationale, same
+// `/api → ${BFF_TARGET:-http://localhost:3000}` rule. The admin app
+// talks to the same BFF (ADR-0020 §"Where does the admin app live"),
+// just at admin-specific paths under `/api/admin/...`; the proxy
+// match on `/api` covers both surfaces.
+//
+// JS form deliberate — only this form can read `process.env` so the
+// Docker / native target swap (BFF_TARGET in dev.compose.yml) works
+// without a rebuild.
+
+const target = process.env['BFF_TARGET'] ?? 'http://localhost:3000';
+
+module.exports = {
+  '/api': {
+    target,
+    secure: false,
+    changeOrigin: true,
+  },
+};

apps/portal-admin/src/environments/environment.ts

@@ -13,13 +13,17 @@
  */
 export const environment = {
   /**
-   * Origin + prefix of the BFF HTTP API. Same value as portal-shell
+   * Prefix of the BFF HTTP API. Same value as portal-shell — both
-   * — both SPAs talk to the same BFF (per ADR-0020 §"Where does
+   * SPAs talk to the same BFF (per ADR-0020 §"Where does the admin
-   * the admin app live"). The admin-specific routing happens via
+   * app live"). The admin-specific routing happens via the
-   * the `AUTH_PATH_PREFIX` token (`/admin/auth`) provided in
+   * `AUTH_PATH_PREFIX` token (`/admin/auth`) provided in
    * `app.config.ts`, not by talking to a different host.
+   *
+   * Relative path: see portal-shell `environment.ts` for the full
+   * rationale. Both SPAs use `proxy.conf.js` to proxy `/api/*` to
+   * the BFF, keeping every call same-origin in the browser.
    */
-  bffApiBaseUrl: 'http://localhost:3000/api',
+  bffApiBaseUrl: '/api',
 
   /**
    * Name of the BFF's CSRF cookie. v1 reuses `portal_csrf`

apps/portal-shell/project.json

@@ -83,6 +83,9 @@
     "serve": {
       "continuous": true,
       "executor": "@angular/build:dev-server",
+      "options": {
+        "proxyConfig": "apps/portal-shell/proxy.conf.js"
+      },
       "configurations": {
         "production": {
           "buildTarget": "portal-shell:build:production"

apps/portal-shell/proxy.conf.js

@@ -0,0 +1,32 @@
+// Angular dev-server proxy for portal-shell.
+//
+// Lets the SPA call `/api/...` as a SAME-ORIGIN request — the dev
+// server intercepts it and proxies to the BFF. Two wins:
+//   - the browser no longer pins the BFF to `localhost:3000`, so the
+//     SPA works when accessed from a different host (e.g. `http://
+//     <vm-ip>:4200/` in the ADR-0030 dockerised dev mode, where the
+//     browser may not be on the same machine as the BFF);
+//   - CORS is bypassed entirely in dev (same origin), so the BFF's
+//     `CORS_ALLOWED_ORIGINS` allowlist no longer has to enumerate the
+//     workstation/VM hostnames a developer might use.
+//
+// Target resolution:
+//   - native `nx serve`        → defaults to http://localhost:3000
+//                                (the BFF on the same machine).
+//   - Compose `apps` profile   → BFF_TARGET=http://portal-bff:3000 is
+//                                set in dev.compose.yml so the proxy
+//                                hits the BFF container by name.
+//
+// JS form (not JSON) is deliberate: it is the only Angular-supported
+// proxy-config form that can read `process.env` at dev-server startup,
+// which is what makes the Docker / native swap work without rebuilds.
+
+const target = process.env['BFF_TARGET'] ?? 'http://localhost:3000';
+
+module.exports = {
+  '/api': {
+    target,
+    secure: false,
+    changeOrigin: true,
+  },
+};

apps/portal-shell/src/environments/environment.ts

@@ -18,12 +18,24 @@
  */
 export const environment = {
   /**
-   * Origin + prefix of the BFF HTTP API. The SPA prepends this to
+   * Prefix of the BFF HTTP API. The SPA prepends this to every
-   * every backend call (`${bffApiBaseUrl}/health`, etc.) and derives
+   * backend call (`${bffApiBaseUrl}/health`, etc.) and derives the
-   * the OTel trace-header propagation pattern from its origin (see
+   * OTel trace-header propagation pattern from its resolved origin
-   * `observability/tracing.ts`).
+   * (see `observability/tracing.ts`).
+   *
+   * Relative path: the Angular dev-server proxies `/api/*` to the
+   * BFF (see `proxy.conf.js`, BFF target overridable via the
+   * `BFF_TARGET` env var — set by the ADR-0030 `apps` Compose
+   * profile to `http://portal-bff:3000`). This keeps every BFF call
+   * same-origin in the browser, so the SPA works whether it is
+   * accessed via `localhost:4200`, the VM IP, or any other host —
+   * and the BFF's `CORS_ALLOWED_ORIGINS` no longer has to enumerate
+   * every developer-side hostname. Production siblings
+   * (`environment.prod.ts`, etc.) may set an absolute origin when
+   * the SPA and BFF live on different hosts; `tracing.ts` resolves
+   * either form against `window.location.origin`.
    */
-  bffApiBaseUrl: 'http://localhost:3000/api',
+  bffApiBaseUrl: '/api',
 
   /**
    * Name of the BFF's CSRF cookie. Mirrors the BFF's

apps/portal-shell/src/observability/tracing.ts

@@ -55,7 +55,13 @@ const SERVICE_VERSION = 'dev';
 // so a deploy-time change to `bffApiBaseUrl` automatically propagates
 // `traceparent` to the right origin. RegExp special chars are escaped
 // before going into the source.
-const bffOrigin = new URL(environment.bffApiBaseUrl).origin;
+//
+// Resolved against `window.location.origin` so a relative
+// `bffApiBaseUrl` (e.g. `/api` for the dev-server proxy in
+// `proxy.conf.js`) yields the current origin; an absolute
+// `bffApiBaseUrl` (e.g. cross-origin production) keeps its own origin
+// (the second `URL` arg is ignored when the first is absolute).
+const bffOrigin = new URL(environment.bffApiBaseUrl, window.location.origin).origin;
 const bffOriginRegex = new RegExp(`^${bffOrigin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/.*`);
 
 const provider = new WebTracerProvider({

infra/local/dev.compose.yml

@@ -261,6 +261,11 @@ services:
   portal-shell:
     <<: *app-base
     container_name: apf-portal-shell-dev
+    environment:
+      # Read by apps/portal-shell/proxy.conf.js — points the dev-server
+      # /api proxy at the BFF container by name (Compose DNS). Native
+      # `nx serve` leaves BFF_TARGET unset and falls back to localhost.
+      BFF_TARGET: http://portal-bff:3000
     command: ['pnpm', 'exec', 'nx', 'serve', 'portal-shell', '--host', '0.0.0.0', '--port', '4200']
     ports:
       - '${SHELL_PORT:-4200}:4200'
@@ -271,6 +276,9 @@ services:
   portal-admin:
     <<: *app-base
     container_name: apf-portal-admin-dev
+    environment:
+      # See portal-shell — same proxy target for the admin SPA.
+      BFF_TARGET: http://portal-bff:3000
     command: ['pnpm', 'exec', 'nx', 'serve', 'portal-admin', '--host', '0.0.0.0', '--port', '4300']
     ports:
       - '${ADMIN_PORT:-4300}:4300'