Raxx · internal docs

internal · gated

Demo flow — client-side only (2026-05-13)

Why the demo runs with the backend OFF

The demo at demo.raxx.app is a marketing surface, not a full-stack slice. For v1, every /api/demo/* call falls through to static fixtures in frontend/trademaster_ui/src/pages/Demo/_fixtures.js when the backend returns 404. No Redis, no Alpaca snapshot, no session storage on the server.

FLAG_DEMO_SESSION is false in backend_v2/api/feature_flags.yaml, so all three backend endpoints (/api/demo/session, /api/demo/propose, /api/demo/paper-fill) return 404 immediately. The client 404-fallback in demoAPI.js catches those and serves mock data instead.

The Cloudflare Pages build variable REACT_APP_FLAGS=demo_flow_ui gates the entire DemoFlow route. When that variable is absent, the /demo route is not registered in App.js and the demo is not reachable.

What each step fakes vs. what will be real post-launch

Step Faked now Real post-launch
1 — Landing Static copy Same copy, live flag
2 — Goal input UI only; inputs stored in sessionStorage Same UI; inputs sent to /api/demo/propose
3 — Strategy choice Fixture proposals from _fixtures.js Live compute from backtest engine
4 — Backtest result Fixture stats Live stats from backtest engine
5 — Fill receipt Fixture fill with UTC timestamp Live simulated fill from /api/demo/paper-fill
6 — Ledger snippet Fixture fill + 2 ghost rows Live fill stored in demo session on server

Known backend blockers (explicitly deferred — do not fix in this PR)

  1. Header mismatch — session_auth.py does not whitelist X-Demo-Session-Token. Requests from demoAPI.js would be rejected by auth middleware even if the backend flag were on.

  2. No Redis for session storage — The demo session endpoint expects a Redis backend for token storage. Redis is not provisioned on the demo Heroku dyno.

  3. DEMO_SNAPSHOT_PATH not set — The propose and paper-fill endpoints read pre-computed historical snapshots from a path that is not configured in any environment.

  4. session_auth exemption missing — /api/demo/* routes are not in the EXEMPT_ROUTES list in session_auth.py, so they would be blocked by the passkey session check before reaching the demo logic.

These are tracked as follow-up work. The client-side fallback is the complete v1 implementation.

How to enable the demo on Cloudflare Pages

Set the build variable:

REACT_APP_FLAGS=demo_flow_ui

Then trigger a Pages rebuild. The /demo route becomes live immediately. No backend changes needed for the mock-data path.