Local Development & Mock Auth

The application uses Google OAuth 2.0 for authentication in production. During local development and automated testing (e.g. AI-assisted visual inspection, Playwright E2E), the OAuth popup cannot be driven by an automated agent.

Mock Auth mode bypasses Google entirely: both the backend and frontend boot with a pre-authenticated dev user, no browser popup required.

Caution

Never enable Mock Auth in production. Both flags default to false and must be set explicitly in your local .env / .env.local files, which are gitignored.

---

How it works

Layer	Flag	Effect
Backend (FastAPI)	MOCK_AUTH=true	get_current_user resolves a DB-backed mock user by email (get-or-create) — no JWT validation
Frontend (Vite/Svelte)	VITE_MOCK_AUTH=true	authStore initialises synchronously with the same mock user — no fetchMe() HTTP call, no loading flash

Default mock identity:

email:      dev@local
name:       Dev User
role:       ADMIN
is_approved: true

Note

Backend mock auth now persists the user in users and reuses it by email in future sessions. This keeps user_id valid for FK-backed writes such as /api/positions, /api/training, and practice attempts.

---

Setup

1. Configure the backend

   Copy .env.example to .env inside backend-api/ and add:

   backend-api/.env

   MOCK_AUTH=true
   MOCK_AUTH_EMAIL=dev@local
   MOCK_AUTH_NAME=Dev User

2. Configure the frontend

   Create frontend-pwa/.env.local (gitignored by Vite) and add:

   frontend-pwa/.env.local

   VITE_MOCK_AUTH=true

3. Start the development servers

   Unified (Recommended)

   # Install runtimes, install all dependencies, and start both servers
   mise install
   mise run setup
   mise run dev
   # → Access locally on http://localhost:5173

   Backend Manual

   cd backend-api
   uv sync --all-extras
   uv run uvicorn dicechess_trainer.main:app --reload --host 0.0.0.0 --port 8000
   # → http://localhost:8000

   Frontend Manual

   cd frontend-pwa
   npm install --legacy-peer-deps
   npm run dev
   # → http://localhost:5173

4. Verify

   Open http://localhost:5173. The app should display the main UI immediately — no Google login popup.

   You can also confirm the backend returns the mock user:

   curl http://localhost:8000/api/auth/me
   # {"id":<mock_user_id>,"email":"dev@local","name":"Dev User","role":"ADMIN","is_approved":true,...}

---

Syncing with Production Data

To test features locally with actual game data and puzzles, you can synchronize your local SQLite database with the latest production backup using our automated synchronization helper scripts.

These scripts use the GitHub CLI (gh) to securely download the latest production database backup artifact from GitHub Actions, verify its integrity, and replace your local development database (backend-api/data/dicechess.db) safely.

Prerequisites

1. Install the GitHub CLI (gh) (e.g. brew install gh on macOS).
2. Authenticate with GitHub by running:

   gh auth login

Running the refresh script

The recommended way to refresh your database is using the unified mise task, which automatically detects your operating system and calls the appropriate helper script:

mise run db:refresh

Alternatively, depending on your preferred terminal shell, you can manually run the scripts from the repository root:

Bash (macOS / Linux)

./scripts/ops/refresh_local_db.sh

PowerShell (macOS / Windows)

./scripts/ops/refresh_local_db.ps1

Note

These scripts automatically remove any active SQLite Write-Ahead Log (-wal) and Shared-Memory (-shm) sidecar files to prevent file lock corruption and ensure a clean, consistent state.

---

Automated testing (AI agents & E2E)

When running Playwright or AI-assisted inspections, set both flags in the test environment before launching the servers. The frontend will render authenticated content on the first paint, making visual assertions predictable.

Note

The backend test suite (pytest) is unaffected — it already overrides get_current_user via FastAPI dependency_overrides in conftest.py, so MOCK_AUTH is never consulted during tests.

---

Troubleshooting: “Failed to save position” in mock mode

If UI shows a generic save error in mock mode, check these in order:

1. Backend really runs with mock auth (backend-api/.env has MOCK_AUTH=true, then restart backend).
2. Frontend really runs with mock auth (frontend-pwa/.env.local or .env has VITE_MOCK_AUTH=true, then restart frontend).
3. Mock user identity is stable (MOCK_AUTH_EMAIL is unchanged while testing bookmarks/training data).
4. Shared game exists in games table (bookmarks have FK to games.game_id).
5. Bookmark is not duplicate (user_id + game_id + ply unique key).

Example SQL checks:

SELECT id, email, role, is_approved FROM users WHERE email = '<mock_auth_email>';
SELECT COUNT(*) FROM games WHERE game_id = '<game_id>';
SELECT id FROM bookmarked_positions
WHERE user_id = <resolved_user_id> AND game_id = '<game_id>' AND ply = <ply>;