← Design notes

The dev loop — localhost to the box

How a change goes from idea to production: built locally, self-tested, your-tested, then shipped to Singapore. The rhythm and the local-server norms that keep it honest.

implement on localhost:8011 → I self-test (simulate real users) → you test → push to the SG box

Self-test before you ever see it

I drive the app the way real users would and watch it behave — not just unit tests.
DeepSeek API for cheap bulk runs; Sonnet sparingly; default to the Claude Code session over API spend.
After any backend change, the safety net: python lib/smoketest.py (unit selftests + HTTP integration).

The local server — port 8011

It must launch against the dev data, or it boots the empty default app.db and nobody can log in (the server still returns 200, so it looks fine):
MAD_DB_PATH=app-dev.db MAD_ROOMS_DIR=rooms-dev
Canonical launcher: scripts\restart8011.bat — kills whatever holds 8011, relaunches in a new console.
Service-worker gotcha: the PWA service worker serves a stale shell, so a UI edit can look like it "didn't take" after a hard refresh — it's the SW, not the server. Use DevTools → "Update on reload", and bump the BUILD badge + sw.js cache on every UI ship.

Test from a phone — LAN

restart8011.bat binds 127.0.0.1 (this PC only). To reach 8011 from a phone or tablet on the same Wi-Fi, run scripts\serve-lan-8011.bat instead — it serves on 0.0.0.0, keeps the dev-data wiring, and prints the http://<LAN-IP>:8011 URL to open on the phone.
It adds a Windows Firewall rule for inbound TCP 8011 (Private profile) — a UAC prompt appears the first time only.
It deliberately leaves the session cookie insecure (MAD_SECURE_COOKIE unset) — that's what lets the phone log in over plain http:// on the LAN.
Caveats: over plain http the PWA service worker won't register (no install/offline on the phone — fine for testing), and the phone must be on the same network (not a guest SSID).

Ship

main is production — no staging. Push every change to origin immediately.
Batch the box deploy (SSH pull + restart) until "deploy" is called — keeps the cross-border SSH footprint small.
The box (Singapore Ali ECS) tracks main; its runtime state (app.db + rooms/) lives outside the repo at /var/lib/mad.

noteThese design notes (room2) are a separate deploy — Cloudflare Pages publishes them on push, independent of the app on the box. So docs and app ship on different paths.

Dialogue · dev loop · localhost → self-test → your test → SG box · see also Deployment topology · The build plan