- proxy Go /api/stream through Nitro; drive /stage, /live, /plan and /forecast from scenario events - fall back to 5 s polling after SSE failures or heartbeat silence; show Live/Polling/Offline - authenticate /control and POST /api/scenario in Nitro with server-side control credentials - add big-screen stage with local QR and a no-login phone recommendation view - add SSE unit tests and a live smoke test; refresh README/Makefile
9.7 KiB
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, Nitronode-server @sit-onyx/nuxt1.2.0+sit-onyx1.22.0for 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
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:
NUXT_API_INTERNAL_BASE=http://localhost:8080 \
PORT=3000 node .output/server/index.mjs
Live demo: /stage, /live, /control
browser ──GET /api/stream──► Nuxt Nitro ──proxy──► Go /api/stream
◄── scenario/ping ── ◄────────── SSE hub
presenter ──POST /api/scenario──► Nitro (Basic auth + control secret) ──► Go
app/composables/useLiveScenario.tsopens oneEventSourceper tab. On ascenarioevent it updates the shared state and tells the page to refetch;pingheartbeats keep the connection marked Live.- After two SSE errors, or when no heartbeat arrives for 32 s (a buffering
proxy), the client closes ranks and polls
GET /api/scenarioevery 5 s. The badge shows Live, Polling or Offline, never a silent stale plan. POST /api/scenariogoes through Nitro; the Go control credentials stay in the Node process./controlitself requires HTTP Basic auth (CONTROL_USER/CONTROL_PASS); a signed cookie lets the page POST without re-prompting./stage,/liveand all public GETs stay open./stagerenders a local SVG QR code (/api/qr) pointing at/live; no third-party QR service is called.
Live stack (read-only Go/ML worktrees)
# 1. ML on 18000 (from ML-py.git/main)
PYTHONPATH=src CONTROL_TOKEN=replace-me-token \
.venv/bin/uvicorn pulsecast.server:app --host 127.0.0.1 --port 18000
# 2. Go on 18080 (from api-go.git/main)
PORT=18080 FASTAPI_URL=http://127.0.0.1:18000 \
CONTROL_USER=control CONTROL_PASS=replace-me-pass CONTROL_TOKEN=replace-me-token \
go run ./cmd/api
# 3. Web preview on 13000 (from this worktree, after npm run build)
PORT=13000 NUXT_API_INTERNAL_BASE=http://127.0.0.1:18080 \
CONTROL_USER=control CONTROL_PASS=replace-me-pass CONTROL_TOKEN=replace-me-token \
node .output/server/index.mjs
# 4. Live smoke: auth boundary, /stage + /live SSR, QR, SSE event,
# polling read, and a staffing/forecast plan that differs from base.
CONTROL_USER=control CONTROL_PASS=replace-me-pass WEB_URL=http://127.0.0.1:13000 \
node scripts/smoke-live.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 |
GET /api/stream |
GET /api/stream, streamed chunk-by-chunk (SSE) |
POST /api/scenario |
POST /api/scenario with server-side control auth |
GET /api/qr?text= |
Local SVG QR generation, no upstream call |
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 |
NUXT_DISABLE_SSE |
unset | 1 forces the polling fallback (SSE failure drill) |
CONTROL_USER / CONTROL_PASS |
unset | Basic auth for /control and POST /api/scenario; also attached to Go /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. /control and
POST /api/scenario require Basic auth at Nitro, and Nitro then attaches the
same credentials to Go. If CONTROL_USER/CONTROL_PASS are unset, the control
surface returns 503 control_auth_unconfigured; public screens keep working.
The K8s web Deployment must mount the same control-auth secret as the API
Deployment:
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
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 |
/stage |
Big-screen decision: headline, peak staff, cost, coverage, QR to /live |
/live |
Phone view: current recommendation, peak shift, scenario, last update |
/control |
Presenter preset buttons; authenticated POST through Nitro |
/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:
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
make check # npm ci, npm run build, npm test
make smoke # Nitro -> Go API contract, against a running web server
make smoke-live # SSE + control + /stage + /live, against the 18080/18000/13000 stack
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.
scripts/smoke-live.mjs proves the live path: unauthorised POST is rejected,
/control authenticates, /stage and /live render server-side, /api/qr
returns SVG, the SSE proxy emits retry: 3000 and the initial scenario, a
presenter POST produces a scenario event (with matching id and version) in
well under 2 s, polling reads the same version, and the target staffing and
forecast responses differ from base. It restores the base scenario at the end.
Docker
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 state is in memory in the single Go pod. A pod restart drops streams;
clients reconnect via
retry: 3000or fall back to 5 s polling. - Raw CSV, secrets and kubeconfig never enter this repository.