gupi-osint-board/docs/routes.md

Routes & how to test (dev)

The front end picks what to render from the URL (see src/main.tsx). Vite dev server runs on http://localhost:5173.

URL	Renders	For
/	Splash → campaign (walks the story graph: cutscene → dialogue → hands off to the board)	Narrative / player flow
/node/<nodeId>	Dev/admin teleport to a story node; a level node lands you on that level's board clone	Jumping around the tree while testing
/level/<levelId>	A level board directly (add ?edit=1 to author)	Board work / editing
/admin	Admin panel (mysteries, NPCs, assets, graph editor)	Authoring
/?phone=1	3D clamshell phone dialer spike	Phone prototype

Game state (demo)

A player's whole state is two things on their playthrough:

• playthroughs.current_node_id — where they are (which node; a level node also has current_level_id, the board clone).
• achievements — what they've earned ((playthrough_id, flag_key, awarded_by_node_id)).

Normal play resolves position via GET /api/playthroughs/current. /node/:id is just the dev override that writes current_node_id (the goto teleport).

Quick test recipes

Play the campaign: open / → New Game → click through the intro/briefing → you land on the board.

Jump straight to a node: /node/<id>. List the current node ids:

docker exec osint-board-db psql postgres://osint:osint_secret@localhost:5432/osint_dev -At -F' | ' \
  -c "SELECT n.id,n.node_type,n.label FROM osint.story_nodes n JOIN osint.mysteries m ON m.id=n.mystery_id WHERE m.slug='glass-harbor' ORDER BY n.ypos;"

(The level row is the board.)

Phone seam (achievements): /?phone=1 → dial 55501 (Elias) → voicemail → click grant elias_number_callable → the handset glows → dial 55501 again → connects. Voss 55502 stays voicemail; other numbers = unobtainable.

Reset to a clean slate: docker exec osint-board-db psql postgres://osint:osint_secret@localhost:5432/osint_dev -c "TRUNCATE osint.playthroughs CASCADE;" then reload (playthroughs + achievements are wiped; / shows the splash again).

Dev-only endpoints

Both are gated to NODE_ENV !== 'production' (swap for the admin JWT when we want them in a deployed build):

• POST /api/playthroughs/:id/goto { nodeId } — teleport (powers /node/:id).
• POST /api/playthroughs/:id/achievements { flagKey } — grant an achievement (stand-in until the server-side rule engine fires them from play). GET the same path lists earned achievements.

Backend changes need a container rebuild: docker compose -f docker-compose.dev.yml up -d --build app. The Vite front end is live on 5173.