# PulseCast web Nuxt 4 SSR frontend for **PulseCast** — a staffing copilot that turns inner-city footfall into a usable next-week shift plan for a Heilbronn retailer. The hero screen is **`/plan`**. The map, weather and forecast are supporting evidence; the decision is the weekly plan. ## Stack - Nuxt `4.6.4`, `ssr: true`, Nitro `node-server` - `@sit-onyx/nuxt` `1.2.0` + `sit-onyx` `1.22.0` for the entire shell and UI - Nitro server routes proxy to the Go API; the browser only talks to this origin - Shared plan heuristic in `shared/staffing.ts`, used for the mock fallback and for the labeled local preview on `/plan` Onyx is used for the navigation/app shell, page layout, cards, tables, buttons, badges, tags, selects, segmented control, slider, stepper, accordion and file upload. The app does not ship a parallel component design system. ## Run ```bash npm ci npm run dev # http://localhost:3000, expects Go at http://localhost:8080 npm run build # production SSR build in .output/ npm run preview # preview the built app npm test # heuristic + Go parity tests ``` The built SSR server can also be started directly: ```bash NUXT_API_INTERNAL_BASE=http://localhost:8080 \ PORT=3000 node .output/server/index.mjs ``` ## API wiring Every route in `server/api/` is a proxy to the Go service. The default is the real API; mock JSON is an explicit dev fallback only. | Nitro route | Upstream | | --- | --- | | `GET /api/healthz` | `GET /api/healthz` | | `GET /api/readyz` | `GET /api/readyz` | | `GET /api/meta` | `GET /api/meta` | | `GET /api/sensors` | `GET /api/sensors` | | `GET /api/context` | `GET /api/context` | | `GET /api/series` | `GET /api/series` | | `GET /api/forecast` | `GET /api/forecast` | | `GET /api/staffing` | `GET /api/staffing` | | `GET /api/scenario` | `GET /api/scenario` | | `POST /api/scenario` | `POST /api/scenario` with server-side control auth | | `POST /api/train` | `POST /api/train` with server-side control auth | | `GET /api/train/:job_id` | `GET /api/train/{job_id}` with server-side control auth | | `GET /api/scenarios` | Local UI metadata only (labels/descriptions) | `/plan` reads Go `/api/staffing` directly. The four local assumption controls (safety factor, minimum staff, shift length, labour cost) are not query inputs of the Go contract, so changing them renders an explicit **local preview** from the API’s forecast hours; “Use API plan” restores the server values. The shared heuristic is tested against a captured Go response in `test/fixtures/go-staffing.json`. ### Environment | Variable | Default | Purpose | | --- | --- | --- | | `NUXT_API_INTERNAL_BASE` | — | Preferred server-side Go base (`http://api:8080` in K8s) | | `NUXT_API_BASE` | — | Alias for the server-side base | | `NUXT_PUBLIC_API_BASE` | — | Fallback base; also exposed to the browser | | `NUXT_API_TIMEOUT_MS` | `8000` | Upstream request timeout | | `NUXT_PUBLIC_USE_MOCK` / `NUXT_USE_MOCK` | unset | `1` enables the mock fallback | | `CONTROL_USER` / `CONTROL_PASS` | unset | Basic auth for `/api/scenario` and `/api/train` | | `CONTROL_TOKEN` | unset | Optional Bearer token for future control auth | | `NUXT_PUBLIC_DEMO_NOW` | `2026-11-14T08:12:00Z` | Replay clock used for labels | Control credentials are read only in the Nitro process. They are never placed in `runtimeConfig.public` and never reach the browser bundle. If they are unset, Go returns `503 control_auth_unconfigured` / `401`; the UI surfaces that error instead of exposing anything. The K8s web Deployment must mount the same `control-auth` secret as the API Deployment: ```yaml env: - name: CONTROL_USER valueFrom: { secretKeyRef: { name: control-auth, key: CONTROL_USER } } - name: CONTROL_PASS valueFrom: { secretKeyRef: { name: control-auth, key: CONTROL_PASS } } ``` ### Mock fallback ```bash NUXT_PUBLIC_USE_MOCK=1 npm run dev ``` Mock mode serves deterministic JSON from `mock/` and completes training immediately. It is for developing the UI without Go; the default and the deployed path are the real API. ## Screens | Route | Purpose | | --- | --- | | `/` | Now: replay reading, 8-sensor schematic, weather, holiday, data versions | | `/forecast` | 7-day daily forecast, uncertainty band, weather strip | | `/plan` | **Hero.** Peak decision, shift blocks, coverage, cost, why, assumptions | | `/simulate` | Base vs scenario plan, both read from Go `/api/staffing` | | `/about` | Method, metrics, limits, privacy, train form | The layout is checked at **390 px** (single column, mobile Onyx nav, day cards) and **1440 px** (Onyx horizontal nav, two-column plan with tables). ## Plan logic `shared/staffing.ts` is the single implementation of the contract heuristic: ```text required = ceil(max(0, footfall) / visitors_per_staff_hour * safety_factor) required = max(required, min_staff) ``` Store hours are 10:00–20:00 Europe/Berlin; default blocks are 4 h; labour cost is €16/h; the default service standard is 25 visitors per staff-hour. The flat schedule applies the global peak requirement to every store hour, matching Go and CONTRACT.md §5. Coverage is at or above requirement by construction because each block is sized to its local peak — the UI shows the resulting overstaffed hours instead of hiding them. ## Checks and CI ```bash make check # npm ci, npm run build, npm test make smoke # against a running web server (WEB_URL=...) ``` The same `make check` runs in Gitea Actions (`.gitea/workflows/ci.yml`). The workflow needs no secrets, no registry push and no cluster access. `scripts/smoke-api.mjs` exercises the Nitro → Go chain: health, sensors, context, meta, series, base and scenario forecasts, standard and premium staffing, local presets, and 404/400 propagation. ## Docker ```bash docker build -t pulsecast-web . docker run --rm -p 3000:3000 \ -e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \ pulsecast-web ``` The multi-stage image copies only `.output/` into `node:22-alpine`. It creates numeric UID/GID **`10001:10001`**, uses `COPY --chown=10001:10001` and runs `USER 10001:10001`. Kubernetes should set `runAsUser: 10001`, `runAsGroup: 10001` (never a named user such as `node`). ## Limits - No POS, sales, queue or payroll data. Cost is an assumption. - Forecast is model output; the plan is decision support, not an optimizer. - Eight sensors in a 580 m cluster; no city-wide heatmap claim. - SSE (`/api/stream`), `/live` and `/stage` are the next worktree. - Raw CSV, secrets and kubeconfig never enter this repository.