Skip to content
uwwoe docs

Dev Demo Loop

Dev Demo Loop

make dev-demo is the human development loop for the local demo. It is separate from the Playwright harness in make test-e2e.

What It Starts

The runner in scripts/dev/demo.mjs writes local artifacts under .dev/demo/ and starts:

  • a local index, preferring the promoted .dev/published/math-engineering-support artifact when it exists, then .dev/math-engineering/candidate-index, then .dev/math/candidate-index;
  • the Go backend on http://127.0.0.1:18081;
  • the SvelteKit Vite dev server on http://127.0.0.1:4173;
  • the Rust/WASM atlas build copied into web/static/atlas-layout-wasm/.

The .dev/ directory is ignored and may be deleted at any time.

Why It Exists

scripts/e2e/start-web-with-backend.sh is intentionally test-shaped: it creates a temporary index and exits when Playwright exits. That is useful for repeatable CI, but it is a poor interactive loop.

make dev-demo keeps Vite in dev mode so Svelte hot module replacement is visible while you edit the frontend. It also watches backend, index-pipeline, fixture, and WASM sources so the demo runtime follows local changes without asking you to rebuild the stack by hand.

The runner now preflights the configured backend and frontend ports before building or starting child processes. If 18081 or 4173 is already occupied, it exits with a clear message instead of entering a restart loop or letting Vite silently move to a different port. Use the port environment variables below for parallel demo stacks.

The runner also prints the selected index path, index id, entity counts, graph projection counts, and a CS 136 pathway probe when the broad candidate is active. If the UI says a surprising number of indexed courses, trust this startup summary and /api/v1/index first: the number is a property of the currently loaded published index artifact, not the current Canva viewport.

Watch Behavior

  • Frontend changes are handled by Vite HMR.
  • Go backend/API changes restart the backend with a short debounce.
  • Demo fixture, parser, validator, or index-builder changes rebuild the demo index and restart the backend when the fixture fallback index is active.
  • When .dev/published/math-engineering-support or .dev/math-engineering/candidate-index is active and .dev/math-engineering/raw exists, parser, validator, index-builder, count policy, or raw snapshot changes rerun parse-math-engineering-snapshot, build-math-engineering-index, and the relevant inspection target before restarting the backend. If the promoted published demo artifact is active, the runner also reruns publish-math-engineering-support-index. This keeps the broad local demo from showing stale parser or graph-projection behavior after a code change.
  • Other explicitly configured prebuilt indexes are treated as external inputs: changes under that index directory restart the backend but do not rerun the scraper/parser pipeline.
  • Rust/WASM layout changes rebuild the WASM artifact. Refresh the page if the worker has already loaded the previous module.
  • The runner uses native filesystem events for watched paths. If a platform cannot provide those events, it falls back to coarse five-second polling so a broad raw snapshot tree is not recursively scanned every second during normal editing.

Configuration

Optional environment variables:

  • UWSCRAPE_DEV_BACKEND_PORT, default 18081.
  • UWSCRAPE_DEV_FRONTEND_PORT, default 4173.
  • UWSCRAPE_DEV_SNAPSHOT_DIR, default testdata/demo-4a.
  • UWSCRAPE_DEV_INDEX_DIR, optional explicit published/candidate index directory. If omitted, the runner uses .dev/published/math-engineering-support when it exists, then .dev/math-engineering/candidate-index, then .dev/math/candidate-index.
  • UWSCRAPE_ALLOW_FIXTURE_DEV_DEMO=1, explicit escape hatch that allows the runner to build .dev/demo/index from UWSCRAPE_DEV_SNAPSHOT_DIR when no broad local candidate exists.
  • UWSCRAPE_ALLOW_SMALL_DEV_INDEX=1, explicit escape hatch for running a configured index with fewer than 100 courses. This exists for tiny regression slices; do not use it for a human product demo.

The runner generates .dev/demo/token.key if it does not exist. The backend CORS allowlist is set for the local Vite origin. The frontend talks to the backend through the SvelteKit /api/v1 proxy, so browser URLs do not expose state tokens.

The .dev/math/candidate-index path is intentionally untracked. Build it from a live, opt-in Math-profile snapshot before using it as evidence of broader course coverage. After .dev/math/raw and .dev/math/parsed exist, run make build-math-index to regenerate .dev/math/validation and .dev/math/candidate-index with the checked count-policy reconciliation. The committed fixture fallback is no longer the silent human-demo default; opt into it with UWSCRAPE_ALLOW_FIXTURE_DEV_DEMO=1 only when you deliberately want the small regression fixture.

The reviewed fetch profiles are documented in docs/operations/index-profile-sources/. For the broader product direction, fetch Math and Engineering with repeated profile flags, then build an explicit candidate index path instead of replacing the committed fixture silently. After .dev/math-engineering/raw and .dev/math-engineering/parsed exist, run make build-math-engineering-index. To promote that candidate into the local published demo slot, run make publish-math-engineering-support-index; make dev-demo prefers that promoted artifact when it is present.

For the current richer local demo, use the opt-in support-subject closure target:

Terminal window
UWSCRAPE_ALLOW_LIVE_WATERLOO=1 make build-math-engineering-support-index

That command performs a live Kuali fetch, so it is intentionally excluded from default checks and CI. It fetches the Math and Engineering profiles plus the reviewed support-subject list documented in docs/operations/index-profile-sources/, then parses, validates, and rebuilds .dev/math-engineering/candidate-index. Before demoing, run make publish-math-engineering-support-index. That command first runs inspect-math-engineering-index, promotes the candidate through the same uwscrape publish-index path used by release tooling, and then runs inspect-math-engineering-published-index. The inspection fails if the artifact has fallen back below the broad local-demo thresholds of 600 courses, 50 credentials, 600 graph-projection course nodes, or a non-shallow CS 136 pathway diagnostic. The pathway gate catches the failure mode where the app appears to have a tiny course universe even though the active index should contain many downstream dependencies.

make dev-demo also runs the matching inspection gate before starting the backend: inspect-math-engineering-published-index for the promoted broad artifact, inspect-math-engineering-index for the broad candidate, inspect-math-index for the narrower Math candidate, or a basic inspect-index for an explicit UWSCRAPE_DEV_INDEX_DIR. A configured index with fewer than 100 courses is rejected unless UWSCRAPE_ALLOW_SMALL_DEV_INDEX=1 or the explicit fixture-demo escape hatch is set. This prevents an old or shallow candidate directory from booting a misleading human demo.

When To Use Each Command

Use make dev-demo while actively working on the demo.

Use make test-e2e when you want Playwright to start its own isolated backend, frontend, and temporary index and then tear them down after the test run.