XAUCORE — DEMO / SYNTHETIC XAUUSD trading simulator

DEMO • SYNTHETIC DATA — no real quotes, no broker, no real accounts, no real trades. Every price, candle, spread, commission, swap, margin figure and news event is generated by the app itself. Nothing connects to a real market.

Deployable on Vercel with a Turso (libSQL) database and per-user cloud save: the whole simulator freezes when you leave the site and resumes exactly where it stopped — 5 minutes, 5 hours or 5 days later, from any device you sign in on.

---

1. Architecture

Layer	Choice	Notes
Frontend	Single self-contained public/index.html (vanilla JS, canvas chart). Unchanged from the original project.	The whole simulator is one S object; that object is the save. Vercel serves public/ statically.
API	One file per route under api/ — standard Vercel serverless functions (@vercel/node, ESM).	api/health.js, api/me.js, api/state.js, api/lock.js, api/owner.js, api/auth/{register,login,logout}.js. Shared code in api/_lib/ (not routed).
Access gate	middleware.js (root, Node runtime) runs before every request. Enforces the "site closed" switch (README §4). Fail-open.	Logic in api/_lib/gate.js, shared with dev-server.js.
Database	Turso / libSQL via @libsql/client. Tables users, sessions, states.	No local file in production (Vercel's FS is read-only). Local dev falls back to file:./data/local.db automatically.
Auth	Email + password (scrypt) — an account is required, there is no guest mode. Opaque random session tokens, 1-year TTL, revocable.	No JWT library.
Sync	localStorage (per-user key xc_state_<id>) = fast cache / offline fallback. Turso = source of truth. Pushed on change (debounced), force-pushed on tab-hide, and a synchronous XHR on pagehide (the ~220 KB state exceeds sendBeacon's 64 KB limit).	Multi-device, offline-tolerant.

The "freeze while away" guarantee

• Day progress and market-regime age are accumulated (day.elapsedMs, regime.ageMs) from active wall-time only, and each frame's delta is capped to one frame — a gap of minutes / hours / days counts as a single 60 ms step, never a leap.
• visibilitychange stops every timer while the tab is hidden. Nothing advances.
• On return the exact saved state is restored (verified byte-for-byte) and the simulation continues from that point the moment you interact with it.

API

POST /api/auth/register   {email,password}      -> {token,id,email}
POST /api/auth/login      {email,password}       -> {token,id,email}
POST /api/auth/logout     (auth)
GET  /api/me              (auth)                 -> {id,email}
GET  /api/state           (auth) [?sid&meta=1]   -> {state,updatedAt,rev,lease}   meta=1 omits the blob
POST /api/state           {op:"claim",sid,force}  (auth) -> {granted,lease}       take the driving lease
PUT  /api/state           {state,sid}  (auth)     -> {updatedAt,rev,lease}  409 if another sid holds it
                                                                    also accepts ?token= (unload beacon)
GET  /api/health                                 -> {ok:true}
GET  /api/lock                                   -> {locked,configured,isOwner}   (see §4)
POST /api/lock            {locked}  (owner cookie)
GET  /api/owner                                  -> {configured,isOwner}
POST /api/owner           {key}                  -> Set-Cookie xc_owner
DELETE /api/owner                                -> clears xc_owner

---

2. Run locally

Requires Node 22+. No Vercel CLI needed — dev-server.js mounts the same api/ handlers on a plain node:http server and serves public/, exactly like Vercel does.

npm install
npm run dev

Open http://localhost:8777. The database is a local SQLite file at ./data/local.db (created automatically) unless you set TURSO_* env vars.

npm run dev also powers the Claude Code preview (.claude/launch.json).

Optional — point local dev at the real cloud DB: copy .env.example to .env, fill in the Turso values, and npm run dev (Node loads .env automatically from v20.6+ only with --env-file; simplest is node --env-file=.env dev-server.js).

Debug: append ?boot=paused to the URL to restore the saved state without advancing the simulation.

---

3. Deploy to Vercel

3.1 Create the Turso database

npm i -g turso              # or: brew install tursodatabase/tap/turso
turso auth signup
turso db create xaucore
turso db show xaucore --url          # -> TURSO_DATABASE_URL   (libsql://xaucore-....turso.io)
turso db tokens create xaucore       # -> TURSO_AUTH_TOKEN

Create the schema once (optional — the app also self-creates it on first request):

TURSO_DATABASE_URL=libsql://... TURSO_AUTH_TOKEN=... npm run init-db

3.2 Ship it

git init && git add -A && git commit -m "XAUCORE on Vercel + Turso"
npm i -g vercel
vercel                     # first run: links/creates the project

In the Vercel project → Settings → Environment Variables add (Production + Preview):

Name	Value
TURSO_DATABASE_URL	libsql://xaucore-....turso.io
TURSO_AUTH_TOKEN	the token from turso db tokens create
OWNER_KEY (optional)	any long random secret — enables the "site closed" mode (see §7)

Then:

vercel --prod

No build step, no framework — Vercel serves public/ statically, runs each api/**/*.js file as a serverless function, and runs middleware.js before page requests. npm install runs automatically.

---

4. "Site closed" mode (maintenance / private access)

A single switch that closes the site to visitors while you keep working on it. Nothing is reset — the simulator, every account and all saved state are untouched; it is purely an access gate.

Enable it: set an OWNER_KEY env var (any long random string) in the Vercel project and redeploy. Without OWNER_KEY the feature is dormant and the site behaves exactly as before.

Use it: open Настройки симулятора → 🔒 Доступ к сайту.

• Not signed in as owner → enter the OWNER_KEY to sign in (sets a signed HttpOnly cookie).
• Signed in as owner → an ON / OFF switch. ON = closed.

What visitors see when closed: a self-contained "Система временно недоступна" page (served by middleware.js with HTTP 503) — no app, no assets, no internal detail. A discreet Доступ владельца link on that page lets you sign in with the OWNER_KEY from anywhere. New sign-ins (/api/auth/login|register) are refused too, so the closed site can't be scripted into.

Why it can't be bypassed: the page check runs in middleware.js, before routing and before any static file is served, so deleting CSS, editing JS in DevTools, or deep-linking an internal route all still hit the gate first (the app is an SPA — every "route" is just /). Owner identity is a HMAC-signed cookie (key = sha256("xaucore-owner-v2|" + OWNER_KEY)) — visible in DevTools but impossible to forge without OWNER_KEY. The state-sync API (/api/state) is left on its normal fast path; it is per-user and token-gated, and a blocked visitor never gets a token.

Toggling does not redeploy. The flag lives in the Turso settings table (site_locked), so ON/OFF takes effect within ~5 seconds with no new deployment and no state change.

Locked out? Two independent recoveries, both instant:

1. Remove the OWNER_KEY env var and redeploy → the gate goes dormant (site fully open).
2. In the Turso DB: DELETE FROM settings WHERE key = 'site_locked'; (or set its value to 0).

Route	Purpose
GET /api/lock	{ locked, configured, isOwner } — public
POST /api/lock {locked}	flip the switch — owner cookie required
GET /api/owner	{ configured, isOwner }
POST /api/owner {key}	validate OWNER_KEY → set owner cookie
DELETE /api/owner	sign out of owner mode

Local dev: OWNER_KEY=whatever npm run dev — dev-server.js runs the same gate.

---

5. Custom domain xaucore.io

1. Vercel project → Settings → Domains → add xaucore.io and www.xaucore.io.
2. At your DNS provider create the records Vercel shows:
   • xaucore.io → A 76.76.21.21 (Vercel's apex IP) or the ALIAS/ANAME Vercel lists.
   • www.xaucore.io → CNAME cname.vercel-dns.com.
3. TLS is issued automatically once DNS verifies. No app change — the API is relative-path only.

---

6. What is saved (per user, in Turso)

Current XAUUSD price · Bid / Ask / Spread · Balance · Equity · Margin · Free Margin · Margin Level · all open positions (volume, entry, SL, TP, swap, commission) · Floating P/L · full trade history + statistics · current simulated Day number · time inside the day · complete Price-Engine state (velocity, EMAs, volatility-cluster) · current Market Regime and its age · every Simulator Setting · Manual Market Control settings · the candle history for every timeframe.

Re-opening the site (same browser or a different device signed into the same account) restores all of it exactly and the simulation carries on from there. Nothing moved while you were gone.

---

7. Verified test scenario

1. Open the site → register an account, then sign in.
2. Trade — open a few positions, set SL/TP.
3. Note price, balance, positions, day, time.
4. Fully close the site (or clear the browser).
5. Re-open → auto-restore (token) or sign in again.
6. Exact match — price / Bid / Ask / balance / equity / positions / SL / TP / day / time / regime / candle count restored byte-for-byte.
7. Continue trading — simulation resumes from that point.
8. While away (loop stopped): price, day time, sim clock, candles — completely frozen; a simulated 5-hour / 5-day gap advances the day by ~60 ms, never a leap.
9. Multi-device: signing into the same account from a fresh browser restores the same state.