docs(portal-self-service): serving/e2e decisions + walking-skeleton demo note (refs #68)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -124,10 +124,12 @@ jobs:
         run: make verify-domain
       - name: BFF → Keycloak + domain + projection
         run: make verify-bff
+      - name: Self-service e2e (Playwright, login → submit → success)
+        run: make verify-e2e
       # Log dump must precede teardown (which removes the containers).
       - name: Dump container logs on failure
         if: failure()
-        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=100 oz-init openzaak nrc-init nrc-web nrc-celery nrc-beat flowable-db flowable-rest flowable-init keycloak acl bff domain projection-db event-subscriber projection-api 2>&1 || true
+        run: docker compose -f infra/docker-compose.yml logs --no-color --tail=100 oz-init openzaak nrc-init nrc-web nrc-celery nrc-beat flowable-db flowable-rest flowable-init keycloak acl bff domain projection-db event-subscriber projection-api self-service 2>&1 || true
       - name: Tear down
         if: always()
         run: make down

.gitignore

@@ -52,3 +52,8 @@ vite.config.*.timestamp*
 vitest.config.*.timestamp*
 
 .angular
+
+# Playwright e2e (installed/generated in-container or on local runs)
+tests/e2e/node_modules/
+tests/e2e/test-results/
+tests/e2e/playwright-report/

Makefile

@@ -10,7 +10,7 @@ COMPOSE    := infra/docker-compose.yml
 # Long-running services with a healthcheck — the smoke polls these for readiness
 # (infra/wait-healthy.sh). One-shot init jobs (oz-init, nrc-init, flowable-init)
 # are not polled; they only need to have run. See docs/runbooks/gitea-actions-gotchas.md.
-WAIT_SVCS  := openzaak nrc-web acl bff domain event-subscriber projection-api
+WAIT_SVCS  := openzaak nrc-web acl bff domain event-subscriber projection-api self-service
 # Config files (OpenZaak data.yaml, Keycloak realms, Flowable BPMN) are streamed
 # into external named volumes via `docker cp` (infra/seed-config.sh) instead of
 # bind-mounted, because bind mounts don't reach sibling containers on the
@@ -153,6 +153,11 @@ verify-domain:
 verify-bff:
 	bash infra/run-bff-check.sh
 
+## verify-e2e: walking-skeleton Playwright e2e (S-08d) against the up stack — DigiD login →
+## submit → confirmation, driven inside the compose network.
+verify-e2e:
+	bash infra/run-e2e-check.sh
+
 ## verify: local mirror of the CI verify-stack job — full stack up once, all checks,
 ## tear down (always). For fast single-concern local iteration use `integration`
 ## (oz-only) or `verify-notifications` (oz+nrc) instead.
@@ -165,7 +170,8 @@ verify:
 	    && bash infra/run-notification-check.sh \
 	    && bash infra/run-projection-check.sh \
 	    && bash infra/run-domain-check.sh \
-	    && bash infra/run-bff-check.sh || rc=$$?; \
+	    && bash infra/run-bff-check.sh \
+	    && bash infra/run-e2e-check.sh || rc=$$?; \
 	  docker compose -f $(COMPOSE) down --volumes >/dev/null 2>&1; \
 	  docker volume rm -f $(CFG_VOLS) >/dev/null 2>&1; \
 	  exit $$rc'

apps/self-service/Dockerfile

@@ -0,0 +1,23 @@
+# Multi-stage build for the self-service portal (Angular → nginx).
+# Build context is the repo root (the app needs the pnpm workspace + libs). See infra/docker-compose.yml.
+FROM node:24-slim AS build
+WORKDIR /src
+RUN corepack enable && corepack prepare pnpm@11.5.2 --activate
+
+# Restore first (cached unless the manifests change).
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json eslint.config.mjs ./
+RUN pnpm install --frozen-lockfile
+
+# Sources (only what the app + its libs need).
+COPY apps/self-service apps/self-service
+COPY libs libs
+RUN pnpm nx build self-service
+
+FROM nginx:1.27-alpine AS runtime
+COPY apps/self-service/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/dist/apps/self-service/browser /usr/share/nginx/html
+# Compose-time OIDC config: the browser (Playwright, on the compose network) reaches Keycloak by
+# service name, so the token issuer matches the BFF's authority (host-consistent, ADR-0010).
+RUN printf '{ "authority": "http://keycloak:8080/realms/digid" }\n' > /usr/share/nginx/html/config.json
+
+EXPOSE 80

apps/self-service/nginx.conf

@@ -0,0 +1,29 @@
+server {
+  listen 80;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Resolve the BFF via Docker's embedded DNS at request time (variable proxy_pass), so nginx starts
+  # even before the BFF is up and picks up restarts — instead of failing to load the config.
+  resolver 127.0.0.11 ipv6=off valid=30s;
+
+  # Same-origin API: proxy the BFF endpoint groups to the bff service. The api-client uses relative
+  # URLs, so the browser calls this origin and nginx forwards to the BFF — no CORS, and the DigiD
+  # token (same-origin) is attached by the app's interceptor (S-08d/ADR-0010).
+  location /self-service/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+  location /openbaar/ {
+    set $bff http://bff:8080;
+    proxy_pass $bff;
+    proxy_set_header Host $host;
+  }
+
+  # SPA fallback — Angular client-side routing.
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

apps/self-service/public/config.json

@@ -0,0 +1,3 @@
+{
+  "authority": "http://localhost:8180/realms/digid"
+}

apps/self-service/src/app/app.config.ts

@@ -7,16 +7,29 @@ import { provideRouter } from '@angular/router';
 import { authInterceptor, provideDigiadAuth } from 'auth';
 import { appRoutes } from './app.routes';
 
-export const appConfig: ApplicationConfig = {
+/** Environment-specific settings fetched from /config.json at startup (see main.ts). */
-  providers: [
+export interface RuntimeConfig {
-    provideBrowserGlobalErrorListeners(),
+  /** The Keycloak `digid` realm issuer as the browser reaches it (dev: localhost; compose: keycloak:8080). */
-    provideRouter(appRoutes),
+  authority: string;
-    provideHttpClient(withInterceptors([authInterceptor()])),
+}
-    // Dev defaults (host ports). The compose-served app overrides these for the stack (S-08d).
+
-    provideDigiadAuth({
+/**
-      authority: 'http://localhost:8180/realms/digid',
+ * Build the app providers from runtime config. `redirectUrl` and `secureApiOrigin` are the app's own
-      redirectUrl: typeof window !== 'undefined' ? window.location.origin : '/',
+ * origin: the app is served same-origin as the BFF (nginx proxies /self-service + /openbaar), so the
-      secureApiOrigin: 'http://localhost:8080',
+ * api-client's relative calls stay same-origin and the token interceptor attaches to them.
-    }),
+ */
-  ],
+export function appConfig(runtime: RuntimeConfig): ApplicationConfig {
-};
+  const origin = typeof window !== 'undefined' ? window.location.origin : '/';
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(appRoutes),
+      provideHttpClient(withInterceptors([authInterceptor()])),
+      provideDigiadAuth({
+        authority: runtime.authority,
+        redirectUrl: origin,
+        secureApiOrigin: origin,
+      }),
+    ],
+  };
+}

apps/self-service/src/main.ts

@@ -1,5 +1,10 @@
 import { bootstrapApplication } from '@angular/platform-browser';
-import { appConfig } from './app/app.config';
 import { App } from './app/app';
+import { appConfig, type RuntimeConfig } from './app/app.config';
 
-bootstrapApplication(App, appConfig).catch((err) => console.error(err));
+// Load environment config before bootstrap so the OIDC authority is set per environment
+// (dev: localhost; compose: keycloak:8080) from a single build — 12-factor (S-08d).
+fetch('config.json')
+  .then((response) => response.json() as Promise<RuntimeConfig>)
+  .then((config) => bootstrapApplication(App, appConfig(config)))
+  .catch((err) => console.error(err));

docs/demo-script.md

@@ -5,6 +5,28 @@ copy-pasteable walkthrough against a local `make up` stack.
 
 ---
 
+## S-08d — Walking skeleton complete: browser → submit, end-to-end
+
+**Outcome:** the self-service portal is served in the stack and the full front-of-house happy path
+runs in a real browser — **mock DigiD login → submit → confirmation** — closing the walking skeleton
+(portal → BFF → domain → Flowable → ACL → OpenZaak, with the openbaar register reading the projection).
+
+```bash
+# 1. Bring the whole stack up (portal served on :8140, BFF :8080, Keycloak :8180).
+make up
+
+# 2. Automated happy path — Playwright, inside the compose network (issuer-consistent):
+make verify-e2e          # → login as jan-burger → submit → "ontvangen" confirmation
+
+# 3. By hand: open the portal, log in as jan-burger / test123, click "Registratie indienen".
+open http://localhost:8140
+```
+
+> The portal is served same-origin with the BFF (nginx proxies `/self-service` + `/openbaar`), so no
+> CORS; the OIDC authority comes from `/config.json` at runtime. See `docs/frontend-decisions.md`.
+
+---
+
 ## S-08c — Self-service submit form (NL Design System + DigiD)
 
 **Outcome:** a zorgprofessional logs in via mock DigiD and submits a BIG registration through the

docs/frontend-decisions.md

@@ -72,3 +72,24 @@ with the submit form (S-08c, #67); any deviation from NL DS will be recorded her
 - **Module boundaries:** replaced the demo eslint `depConstraints` (`scope:shop`/`scope:shared`, left
   over from the Nx angular template) with a permissive `*` default; scope/type tags can be
   introduced when the portal set grows.
+
+---
+
+## Serving + e2e (S-08d, #68)
+
+- **Served by nginx, same-origin as the BFF.** The compose `self-service` image serves the built app
+  and **reverse-proxies** `/self-service/*` + `/openbaar/*` to the `bff` service. Because the
+  api-client uses **relative URLs**, the browser calls the app's own origin → nginx forwards to the
+  BFF: **no CORS**, and the DigiD token (same-origin) is attached by the interceptor. nginx resolves
+  the BFF at request time (a `resolver` + variable `proxy_pass`) so it starts before the BFF is up.
+- **Runtime config.** The app fetches `/config.json` before bootstrap (`main.ts`); `appConfig` is a
+  factory. The dev default (`public/config.json`) points at `localhost:8180`; the Docker image bakes
+  the compose value (`keycloak:8080`). One build, per-environment OIDC authority.
+- **e2e runs inside the compose network.** `infra/run-e2e-check.sh` runs Playwright in a `node`
+  container on `cg`, so the browser reaches Keycloak as `keycloak:8080` — the **same issuer** the BFF
+  validates against (resolves the browser-vs-container mismatch, ADR-0010). Chromium is installed at
+  runtime, so there's no Playwright-image-version pinning to keep in sync. The spec is copied in
+  (`docker cp`), not mounted, so it leaves nothing root-owned on the host. Wired as `verify-e2e` in
+  the `verify-stack` CI job.
+- `tests/e2e` is a standalone Playwright project (its own `package.json`), not an Nx project — it's a
+  live-stack check like the other `verify-*` runners, not part of the `frontend` unit lane.

infra/docker-compose.yml

@@ -433,6 +433,30 @@ services:
         condition: service_healthy
     networks: [cg]
 
+  # ── Self-Service portal (S-08d) ────────────────────────────────────────────
+  # nginx serves the Angular app and reverse-proxies /self-service + /openbaar to the BFF
+  # (same-origin, no CORS). The Playwright e2e drives it inside this network so the DigiD
+  # token issuer (keycloak:8080) matches the BFF's authority (ADR-0010).
+  self-service:
+    build:
+      context: ..
+      dockerfile: apps/self-service/Dockerfile
+    image: register-referentie/self-service:dev
+    ports:
+      - "8140:80"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost/ || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    depends_on:
+      bff:
+        condition: service_healthy
+      keycloak:
+        condition: service_started
+    networks: [cg]
+
 volumes:
   oz-db:
   nrc-db:

infra/run-e2e-check.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+#
+# Walking-skeleton e2e (S-08d) against an ALREADY-RUNNING full stack: drive the self-service portal
+# in a real browser through mock-DigiD login → submit → confirmation (login → BFF → domain).
+#
+# Runs Playwright INSIDE the compose network (a node container on `cg`), so the browser reaches
+# Keycloak by service name (keycloak:8080) — the same authority the BFF validates against, so the
+# token issuer matches (ADR-0010). The spec is copied into the container (docker cp), not mounted,
+# so it leaves no root-owned files on the host. The caller owns stack bring-up + teardown.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+root="$(cd "$here/.." && pwd)"
+
+ss="$(docker ps -q --filter 'name=self-service' | head -1)"
+[ -n "$ss" ] || { echo "ERROR: no running self-service container — bring the stack up first" >&2; exit 1; }
+net="$(docker inspect -f '{{range $k,$_ := .NetworkSettings.Networks}}{{$k}}{{"\n"}}{{end}}' "$ss" | head -1)"
+echo ">> running Playwright e2e on network $net against http://self-service"
+
+cid="$(docker create --network "$net" -w /e2e --ipc=host \
+  -e SELF_SERVICE_URL=http://self-service \
+  node:24 sh -c 'npm install --no-audit --no-fund && npx playwright install --with-deps chromium && npx playwright test')"
+trap 'docker rm -f "$cid" >/dev/null 2>&1 || true' EXIT
+docker cp "$root/tests/e2e/." "$cid:/e2e" >/dev/null
+docker start -a "$cid"

tests/e2e/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "e2e",
+  "private": true,
+  "description": "Playwright walking-skeleton e2e (S-08d) — run inside the compose network by infra/run-e2e-check.sh.",
+  "devDependencies": {
+    "@playwright/test": "1.61.1"
+  }
+}

tests/e2e/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// The e2e runs inside the compose network (infra/run-e2e-check.sh); baseURL defaults to the
+// self-service service. Keep timeouts generous — the first navigation triggers the DigiD flow.
+export default defineConfig({
+  testDir: '.',
+  timeout: 90_000,
+  expect: { timeout: 15_000 },
+  retries: 1,
+  reporter: [['list']],
+  use: {
+    baseURL: process.env.SELF_SERVICE_URL ?? 'http://self-service',
+    trace: 'on-first-retry',
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+});

tests/e2e/registration.spec.ts

@@ -0,0 +1,21 @@
+import { expect, test } from '@playwright/test';
+
+// Walking-skeleton happy path (S-08d): a zorgprofessional logs in via mock DigiD and submits a
+// registration through the self-service portal → BFF → domain. The confirmation shows the reference.
+test('DigiD login → submit → confirmation', async ({ page }) => {
+  // Visiting the guarded page redirects to the Keycloak (mock DigiD) login.
+  await page.goto('/');
+
+  // Keycloak's default login form (stable ids across themes).
+  await page.locator('#username').fill('jan-burger');
+  await page.locator('#password').fill('test123');
+  await page.locator('#kc-login').click();
+
+  // Back on the portal, authenticated.
+  await expect(page.getByRole('heading', { name: /Zelfservice/i })).toBeVisible();
+
+  await page.getByRole('button', { name: /indienen/i }).click();
+
+  // The BFF accepted it and the page shows the confirmation.
+  await expect(page.getByText(/ontvangen/i)).toBeVisible();
+});