regress/README.md

# Regress

A location-based capture game in the spirit of *Ingress*, built as a nostr-native
web app. Real Bitcoin-accepting businesses from [BTC Map](https://btcmap.org)
stand in for Ingress's portals — players physically visit them to claim them
for their team (orange or green), then link claimed places into triangular
control fields. First scope: **Madeira, Portugal**.

See [`DESIGN.md`](./DESIGN.md) for the full research/design writeup.

## Stack

- `server/` — Fastify + better-sqlite3 + nostr-tools (TypeScript), same pattern
  as [podsteadr](http://146.59.87.168:3000/ssmithx/podsteadr).
- `frontend/` — Vue 3 + Vite + Pinia + Tailwind + Leaflet.
- Auth is NIP-98 (signed-event login → session cookie), same as podsteadr.
  `frontend/public/nostr-provider.js` is vendored so the app can also be
  launched identity-aware from inside an Archipelago dashboard, the same way
  as podsteadr — see that repo's README for how the registration side works.

## Running locally

```bash
# server
cd server
npm install
npm run dev        # http://localhost:8096

# frontend (separate terminal)
cd frontend
npm install
npm run dev         # http://localhost:5173, proxies /api to :8096
```

On first run, the `places` table is empty — call `POST /api/sync` (or click
"Sync from BTC Map" in the UI) to pull the current Madeira dataset from BTC
Map's public API.

## Game rules (v0)

- Claiming or linking from a place requires being within `CLAIM_RADIUS_METERS`
  (default 40m) of it, via browser geolocation — no claiming from the couch.
- Claiming an enemy-held place captures it for your team and tears down any
  links running through it.
- A link can be created between any two places your team currently holds,
  as long as you're standing at the origin place — no maximum link distance.
- A new link can't cross any existing link (either team) — same as Ingress.
  Links sharing an endpoint don't count as crossing. See
  `services/geo.ts#segmentsIntersect` and `routes/links.ts`.
- Three mutually-linked, same-team places form a field (computed live, not
  stored) — see `server/src/services/fields.ts`.
- Team choice is one-way once made.

## Tests

```bash
cd server
npm test
```

## Deployment

Live at **`https://podsteadr.atobitcoin.io/regress/`** — same public host as
[podsteadr](http://146.59.87.168:3000/ssmithx/podsteadr), reached via a path
prefix under the existing domain/cert rather than its own subdomain (no DNS
access to add one). Migrated here from an earlier `archy-x250-dev3` trial
deploy (Tailscale-only Archipelago node) — see git history for that phase.

- Single container (`Dockerfile`, server + built frontend in one image),
  `podman run --restart unless-stopped`, data bind-mounted at
  `/var/lib/archipelago/regress-data` on the host, internal port **8199**
  (bound to `127.0.0.1` only — nginx is the only way in).
- `deploy/nginx-podsteadr-regress.conf` — the `location /regress/` block
  added to podsteadr's existing nginx site.

### Path-prefix deployment (`ROUTE_PREFIX` / `VITE_BASE`)

Since `/` on this domain is already podsteadr, Regress needed to support
being served from a path prefix — this took two coordinated changes, both
required together:

1. **Frontend build**: `VITE_BASE=/regress/` (Vite's `base` config) so built
   asset URLs and the vendored `nostr-provider.js` script tag/data
   attributes (via `%BASE_URL%` in `index.html`) resolve under the prefix.
2. **Backend runtime**: `ROUTE_PREFIX=/regress` env var — every route
   (including `/api/health`) is registered under this prefix via Fastify's
   plugin-encapsulation `{ prefix }` option (`app.ts`).

**The nginx location must forward the full prefixed path unchanged — do
NOT strip it**, unlike podsteadr's own `/player/`, `/hls/`, etc. blocks
which all strip their prefix (`proxy_pass http://127.0.0.1:PORT/;` with a
trailing slash). Regress's NIP-98 login signs the *exact* URL it's about to
call, prefix included (`frontend/src/lib/api.ts#apiUrl`); if nginx stripped
the prefix before forwarding, the backend would reconstruct a different
(unprefixed) URL to check the signature against, and every login would fail
with "u tag does not match the request URL". So the location block uses
`proxy_pass http://127.0.0.1:8199;` — **no trailing path at all** — which
tells nginx to forward the original URI verbatim, prefix included. This is
covered by `server/src/routePrefix.test.ts`, including a negative test that
a signed-for-the-unprefixed-URL login is correctly rejected (proving the
prefix check is real, not accidentally bypassed).

Deploying at root (no prefix) needs neither variable — both default to `''`/`'/'`.

### Migrating the SQLite database between hosts

The whole game state (places/claims/links/users) is one file,
`regress.sqlite3`. To move it: stop the container, copy the file (plus its
`-wal`/`-shm` siblings if present, or checkpoint first), start the new
container pointed at the copy. No export/import tooling needed — see git
history for the exact commands used for the archy-x250-dev3 → podsteadr
machine move.

To redeploy after a code change: `git pull` in
`/var/lib/archipelago/regress-src` on the host, then:

```bash
podman build --build-arg VITE_BASE=/regress/ --build-arg ROUTE_PREFIX=/regress \
  -t localhost/regress:latest .
podman run -d --name regress-app --replace --restart unless-stopped \
  -p 127.0.0.1:8199:8199 \
  -v /var/lib/archipelago/regress-data:/data \
  -e ROUTE_PREFIX=/regress \
  -e PUBLIC_URL=https://podsteadr.atobitcoin.io \
  localhost/regress:latest
```