chess-web

No-account chess puzzle trainer built as a pnpm monorepo. It serves PGN-based tactical puzzles with variation trees, validates moves on the server, keeps recent-session history, and adds optional browser-side Stockfish evaluation for replay and study.

Highlights

• PGN puzzle import with full variation-tree support
• Server-side move validation and session orchestration
• Explore and mainline solving modes
• Puzzle history with replay, previous/next transport, tree review, and direct loading by public ID
• Optional autoplay, auto-next, one-try mode, restart-in-place, hints, reveal, skip variation, and auto-queen
• Lichess-style PGN explorer review with back/forward/live navigation
• Browser Stockfish eval bar, prepared instant hints, and local UI preferences
• Adjustable animation speed alongside theme and presentation settings
• Multilingual UI with native-language labels and RTL handling
• Local Postgres support with pg-mem fallback for lightweight development

Screenshots

Light Mode

Dark Mode

Zen Mode

Stack

• Frontend: React, Vite, TypeScript, Chessground
• Backend: Fastify, TypeScript, Postgres
• Shared domain logic: packages/chess-core
• Database layer: packages/db
• Shared config/helpers: packages/config
• Workspace tooling: pnpm

Repo Layout

• apps/web: React client
• apps/api: Fastify API
• packages/chess-core: PGN parsing and puzzle/session engine logic
• packages/db: migrations, repositories, DB client
• packages/config: shared env/config helpers
• docs: architecture and flow documentation
• ops: deployment and operations notes
• assets: screenshots and app icon

Quick Start

1. Copy the example env file:

cp .env.example .env

2. For zero-setup local development, set this in .env:

DATABASE_URL=pgmem://local

3. Install dependencies:

npx pnpm@10.5.2 install

4. Start both apps:

./start.sh

Default local URLs:

• Web: http://localhost:5173
• API: http://localhost:3001
• Health check: http://localhost:3001/health

start.sh waits for both services to become reachable and stops them together on Ctrl+C.

Environment Notes

The example env file includes the main runtime settings:

• API_PORT, API_HOST
• VITE_API_BASE_URL
• DATABASE_URL
• COOKIE_SECRET
• ALLOWED_ORIGINS
• IMPORT_TOKEN
• SEED_PGN_FILE
• SEED_MAX_PUZZLES

In non-production mode, if the configured Postgres database is unavailable, the API falls back to in-memory pg-mem.

Database And Puzzle Import

The API can run against either:

• Postgres via DATABASE_URL
• in-memory pgmem://local for development

Run migrations manually:

npx pnpm@10.5.2 --filter @chess-web/api migrate

Import a PGN file from the CLI:

npx pnpm@10.5.2 --filter @chess-web/api import:pgn -- --file /path/to/puzzles.pgn --token "$IMPORT_TOKEN"

Bundled puzzle data also exists at puzzle_exports/stack_min_2plies_256k.pgn.

If SEED_PGN_FILE is set and the puzzle table is empty, the API can seed puzzles automatically on startup.

Useful Commands

From the repo root:

npx pnpm@10.5.2 -r typecheck
npx pnpm@10.5.2 -r lint
npx pnpm@10.5.2 -r test
npx pnpm@10.5.2 -r build

Or run the helper build script:

./build.sh

Run apps separately:

npx pnpm@10.5.2 --filter @chess-web/api dev
npx pnpm@10.5.2 --filter @chess-web/web dev

Puzzle UX Notes

• Restarting a solved puzzle resets the current session in place instead of creating a duplicate history entry.
• Hint previews are prepared when a puzzle loads so the first hint action can appear immediately.
• The PGN explorer supports in-line review plus back, forward, and live-position controls.
• Animation speed is configurable from the settings panel and affects both board motion and puzzle feedback timing.

API Surface

Session routes:

• POST /api/v1/session/start
• POST /api/v1/session/load
• POST /api/v1/session/restart
• POST /api/v1/session/move
• POST /api/v1/session/hint
• POST /api/v1/session/reveal
• POST /api/v1/session/skip-variation
• POST /api/v1/session/next
• POST /api/v1/session/prefetch-next
• POST /api/v1/session/history
• POST /api/v1/session/history/clear
• POST /api/v1/session/tree

Puzzle and admin routes:

• GET /api/v1/puzzles/count
• GET /api/v1/admin/import-status
• POST /api/v1/admin/import-bundled
• GET /api/v1/puzzles/:publicId/tree in non-production debug mode
• GET /health

The admin import routes require x-import-token to match IMPORT_TOKEN.

Documentation

• docs/README.md
• docs/architecture.md
• docs/api-and-session-flow.md
• docs/frontend-flow.md
• docs/database-model.md
• ARCHITECTURE.md

Licensing

• Repository licenses: LICENSE, LICENSE.txt
• Piece asset notice: apps/web/public/pieces/cburnett/NOTICE.txt
• Sound pack notices:
  • apps/web/public/sounds/lichess-standard/LICENSE.txt
  • apps/web/public/sounds/lichess-sfx/LICENSE.txt
• Curated runtime dependency notices: THIRD_PARTY_LICENSES.json

Regenerate the curated runtime notice file with:

node scripts/generateThirdPartyLicenses.mjs

Notes

• Browser-side anti-download prevention is only best-effort.
• The app uses rate limiting and avoids bulk export-style puzzle endpoints.
• The default runtime audio pack is lichess-standard.
• Deployment notes live in ops/oracle-cloudflare.md.