From 66b80a62fb4b515d0ed540230c12699fb118f04d Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 14 Nov 2026 09:16:19 +0100 Subject: [PATCH] docs: tighten README quick start and stale comments - Lead with purpose and exact local/CI commands. - Remove local absolute paths, stale auth notes and unverified claims. - Keep comments to the reason or invariant they protect. --- README.md | 102 +++++++++++++++++------------- app/pages/about.vue | 2 +- app/pages/control.vue | 2 +- app/pages/index.vue | 7 +- app/pages/live.vue | 1 + app/pages/plan.vue | 3 +- server/api/stream.get.ts | 8 +-- server/api/train.post.ts | 3 +- server/middleware/control-auth.ts | 6 +- server/utils/api.ts | 15 ++--- server/utils/mock-data.ts | 5 +- server/utils/train-jobs.ts | 3 +- shared/staffing.ts | 6 +- shared/types.ts | 3 +- 14 files changed, 82 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 2d6a0d2..a9fecb7 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,38 @@ # 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. +Nuxt 4 SSR frontend for **PulseCast**, a staffing copilot that turns inner-city +footfall into a next-week shift plan for a Heilbronn retailer. `/plan` is the +decision surface; `/stage` and `/live` present that plan. The map, weather and +forecast are supporting evidence. -The hero screen is **`/plan`**. The map, weather and forecast are supporting -evidence; the decision is the weekly plan. +## Quick start + +Node 22 is the CI and Docker version. Real data comes from the Go API on +`http://localhost:8080`; mock mode needs no API. + +```bash +npm ci +npm run dev # http://localhost:3000 +``` + +Without the Go API, use the checked-in mock data: + +```bash +NUXT_PUBLIC_USE_MOCK=1 npm run dev +``` + +Build and test exactly as CI does: + +```bash +make check # npm ci, npm run build, npm test +``` + +The built SSR server can also be started directly: + +```bash +NUXT_API_INTERNAL_BASE=http://localhost:8080 \ + PORT=3000 node .output/server/index.mjs +``` ## Stack @@ -18,40 +46,24 @@ 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 -``` - ## Live demo: `/stage`, `/live`, `/control` ```text browser ──GET /api/stream──► Nuxt Nitro ──proxy──► Go /api/stream ◄── scenario/ping ── ◄────────── SSE hub -presenter ──POST /api/scenario──► Nitro (Basic auth + control secret) ──► Go +presenter ──POST /api/scenario──► Nitro (Basic auth + control credentials) ──► Go ``` - `app/composables/useLiveScenario.ts` opens one `EventSource` per tab. On a `scenario` event it updates the shared state and tells the page to refetch; `ping` heartbeats 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/scenario` every 5 s. The - badge shows **Live**, **Polling** or **Offline**, never a silent stale plan. + proxy), the client starts polling `GET /api/scenario` every 5 s. The badge + shows **Connecting**, **Live**, **Polling** or **Offline**, never a silent + stale plan. - `POST /api/scenario` goes through Nitro; the Go control credentials stay in the Node process. `/control` itself requires HTTP Basic auth - (`CONTROL_USER`/`CONTROL_PASS`); a signed cookie lets the page POST without + (`CONTROL_USER`/`CONTROL_PASS`); an HMAC cookie lets the page POST without re-prompting. `/stage`, `/live` and all public GETs stay open. - `/stage` renders a local SVG QR code (`/api/qr`) pointing at `/live`; no third-party QR service is called. @@ -102,11 +114,11 @@ real API; mock JSON is an explicit dev fallback only. | `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 +`/plan` reads Go `/api/staffing` through Nitro. 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 plan’s hourly footfall; “Use API plan” restores the +server values. The shared heuristic is tested against a captured Go response in `test/fixtures/go-staffing.json`. ### Environment @@ -120,14 +132,15 @@ heuristic is tested against a captured Go response in | `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 | +| `CONTROL_TOKEN` | unset | Optional Bearer fallback when Basic is not configured; the Go control API requires Basic today | | `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. +same credentials to Go. In API mode, 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: @@ -163,8 +176,8 @@ deployed path are the real API. | `/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). +The layout targets **390 px** (single column, mobile Onyx nav, day cards) and +**1440 px** (Onyx horizontal nav, two-column plan with tables). ## Plan logic @@ -178,9 +191,9 @@ 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. +and the contract (§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 @@ -200,19 +213,22 @@ 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. +presenter POST produces a `scenario` event (with matching `id` and version) +within the 2 s contract target (the script warns if slower), polling reads the +same version, and the target staffing and forecast responses differ from base. +It restores the base scenario at the end. ## Docker ```bash -docker build -t pulsecast-web . +docker build -t pulsecast-web:local . docker run --rm -p 3000:3000 \ -e NUXT_API_INTERNAL_BASE=http://host.docker.internal:8080 \ - pulsecast-web + pulsecast-web:local ``` +On Linux, add `--add-host=host.docker.internal:host-gateway` or use the host IP. + 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`, diff --git a/app/pages/about.vue b/app/pages/about.vue index e6a91f5..2021e67 100644 --- a/app/pages/about.vue +++ b/app/pages/about.vue @@ -121,7 +121,7 @@ const usingMock = computed(() => ['1', 'true'].includes(String(config.public.use diff --git a/app/pages/control.vue b/app/pages/control.vue index 7e4bf36..103dcd5 100644 --- a/app/pages/control.vue +++ b/app/pages/control.vue @@ -98,7 +98,7 @@ async function apply(preset: ScenarioPreset) {
Scenario presets

- The enum is fixed by CONTRACT.md. Weather and event values match the demo narrative. + The enum is fixed by the API contract. Weather and event values match the demo narrative.

server proxy diff --git a/app/pages/index.vue b/app/pages/index.vue index 43c6c84..b3059ca 100644 --- a/app/pages/index.vue +++ b/app/pages/index.vue @@ -139,8 +139,9 @@ const latestPulse = computed(() => {

- The CSV is static. The replay clock is {{ formatDateTime(demoNow) }}; the last measured point is - {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}. No live sensor feed is claimed. + This is a replay snapshot, not a live sensor feed. The replay clock is + {{ formatDateTime(demoNow) }}; the last measured point is + {{ lastPoint ? formatDateTime(lastPoint.t) : '—' }}.

@@ -149,7 +150,7 @@ const latestPulse = computed(() => {
Sensor cluster

- Select a sensor to update the reading. Bounds are relative; the basemap is the next map slice. + Select a sensor to update the reading. Positions are relative; this is not a geographic map.

580 m cluster diff --git a/app/pages/live.vue b/app/pages/live.vue index 9204f35..8528700 100644 --- a/app/pages/live.vue +++ b/app/pages/live.vue @@ -36,6 +36,7 @@ const { })), }) +// Same scenario id with a new version: refresh because the query string does not move. let lastScenarioId = live.scenarioId watch( () => live.revision, diff --git a/app/pages/plan.vue b/app/pages/plan.vue index 536ba68..dec4fb6 100644 --- a/app/pages/plan.vue +++ b/app/pages/plan.vue @@ -109,8 +109,7 @@ const EMPTY_PLAN: StaffingResponse = { context_version: '', } -// The hero plan comes from the Go API. Local assumption edits only render a -// preview from the API's own forecast hours; they never replace the API plan. +// The Go plan is the source; assumption edits render a local preview only. const { data: apiPlanData, status, diff --git a/server/api/stream.get.ts b/server/api/stream.get.ts index ab4dc80..768424d 100644 --- a/server/api/stream.get.ts +++ b/server/api/stream.get.ts @@ -1,12 +1,8 @@ import { apiBaseUrl, isMockMode } from '../utils/api' /** - * Same-origin SSE proxy. The browser never talks to Go directly, so the - * Cloudflare/K8s CORS surface stays closed and the stream can be cached or - * authenticated at one edge only. - * - * h3's proxyRequest pipes response chunks as they arrive (it does not await - * the full body), which preserves the 15 s heartbeat and `retry: 3000`. + * Same-origin SSE proxy: the browser talks only to Nitro, so CORS stays closed. + * proxyRequest forwards chunks as they arrive, preserving heartbeats and retry hints. */ export default defineEventHandler(async (event) => { if (isMockMode() || process.env.NUXT_DISABLE_SSE === '1') { diff --git a/server/api/train.post.ts b/server/api/train.post.ts index 0725f49..716311a 100644 --- a/server/api/train.post.ts +++ b/server/api/train.post.ts @@ -35,8 +35,7 @@ export default defineEventHandler(async (event) => { } } - // Stream the multipart CSV to Go unchanged. The control credentials are - // attached by the Nitro process and never reach the browser bundle. + // Forward the raw multipart CSV to Go; control credentials stay in this process. const contentType = getRequestHeader(event, 'content-type') ?? '' if (!contentType) { throw createError({ diff --git a/server/middleware/control-auth.ts b/server/middleware/control-auth.ts index 2160b51..5f2bbb6 100644 --- a/server/middleware/control-auth.ts +++ b/server/middleware/control-auth.ts @@ -39,10 +39,8 @@ function isProtected(event: import('h3').H3Event): boolean { } /** - * Presenter-only control surface. Basic auth is checked in Nitro; on success - * an HMAC cookie (signed with CONTROL_PASS) lets the page POST /api/scenario - * without re-prompting. The browser never receives the Go credentials, and - * /stage, /live and all public GETs stay open. + * Presenter control: Basic auth at Nitro, then an HMAC cookie (signed with + * CONTROL_PASS) lets /control POST without re-prompting. Public GETs stay open. */ export default defineEventHandler((event) => { if (!isProtected(event)) return diff --git a/server/utils/api.ts b/server/utils/api.ts index ef66820..c15087d 100644 --- a/server/utils/api.ts +++ b/server/utils/api.ts @@ -1,6 +1,5 @@ -// Server-side Go API client. Every Nitro route uses this module so the browser -// only ever talks to the Nuxt origin: the Go base URL and the control -// credentials stay in the Node process. +// Server-side Go API client. Nitro routes use it so the browser only talks to +// this origin and control credentials stay in the Node process. interface ApiErrorEnvelope { error?: { code?: string; message?: string } @@ -39,7 +38,7 @@ export function apiBaseUrl(): string { ).replace(/\/+$/, '') } -/** True only when NUXT_USE_MOCK=1 / NUXT_PUBLIC_USE_MOCK=1 is set. */ +/** Mock mode is opt-in via NUXT_USE_MOCK or NUXT_PUBLIC_USE_MOCK (1/true). */ export function isMockMode(): boolean { const config = useRuntimeConfig() const raw = @@ -54,8 +53,7 @@ function controlAuthorization(): string | undefined { if (user && pass) return `Basic ${Buffer.from(`${user}:${pass}`).toString('base64')}` const token = envValue('CONTROL_TOKEN', 'NUXT_CONTROL_TOKEN') || String(config.controlToken ?? '') - // Go currently validates Basic auth; Bearer is accepted here for the future - // token-based control surface without exposing the token to the browser. + // Go requires Basic today; Bearer is a fallback for a future token-based API. if (token) return `Bearer ${token}` return undefined } @@ -121,10 +119,7 @@ export async function apiRequest(path: string, options: ApiRequestOptions = { return response._data as T } -/** - * Forward a request body (training upload) and preserve Go's status code and - * JSON body, including 202/400/409/502 responses that are part of the flow. - */ +/** Forward a training upload and keep Go's status code for 202/4xx/5xx. */ export async function apiForward( event: import('h3').H3Event, path: string, diff --git a/server/utils/mock-data.ts b/server/utils/mock-data.ts index 1f99922..2a7e752 100644 --- a/server/utils/mock-data.ts +++ b/server/utils/mock-data.ts @@ -1,6 +1,5 @@ -// Server-side mock dataset. Shapes follow /home/noel/Documents/Hackathon_2026/CONTRACT.md. -// The files are imported (not read from disk at runtime) so the Nitro build bundles them -// into the SSR output and the app renders before the Go API exists. +// Server-side mock dataset. Shapes follow the Go API contract; files are imported +// so Nitro bundles them and mock mode renders without the Go API. import context from '../../mock/context.json' import demo from '../../mock/demo.json' import meta from '../../mock/meta.json' diff --git a/server/utils/train-jobs.ts b/server/utils/train-jobs.ts index c67f5fe..1845712 100644 --- a/server/utils/train-jobs.ts +++ b/server/utils/train-jobs.ts @@ -18,8 +18,7 @@ export function createMockTrainJob(model: 'small' | 'forecast', filename: string const now = new Date().toISOString() const job: MockTrainJob = { job_id: `mock-${Date.now().toString(36)}`, - // The mock completes immediately. Replace this with polling of GET /api/train/{job_id} - // once the Go/FastAPI service exists. + // The mock completes immediately; the real path polls GET /api/train/{job_id}. status: 'succeeded', model, started_at: now, diff --git a/shared/staffing.ts b/shared/staffing.ts index 2c64fe1..9905ce0 100644 --- a/shared/staffing.ts +++ b/shared/staffing.ts @@ -84,11 +84,7 @@ export function hhmm(hour: number): string { return `${String(hour).padStart(2, '0')}:00` } -/** - * Mock scenario behaviour. The contract defines the scenario enum but not the - * size of each perturbation; these multipliers are demo assumptions and are - * shown in the UI. The Go/ML implementation must publish the same numbers. - */ +/** Demo perturbations for the mock fallback; the Go API applies scenarios from ML output. */ export function applyScenario(points: Point[], scenario: Scenario): Point[] { if (scenario === 'base') return points return points.map((point) => { diff --git a/shared/types.ts b/shared/types.ts index a8926c5..f636ab0 100644 --- a/shared/types.ts +++ b/shared/types.ts @@ -1,5 +1,4 @@ -// Canonical shapes from /home/noel/Documents/Hackathon_2026/CONTRACT.md (v1 draft). -// Keep these in sync with the Go API; the UI consumes exactly these fields. +// Canonical wire shapes for the Go API; keep them in sync with the contract. export const HORIZONS = ['15m', '1h', '48h', '7d'] as const export type Horizon = (typeof HORIZONS)[number]