ChessView

ChessView is a full-stack educational chess web application. It demonstrates authenticated play, server-authoritative game state, WebSocket events, PostgreSQL persistence, local browser analysis, puzzles, tournaments, scheduled matches, and an admin surface.

Repository: https://github.com/thefueki/chessview Current baseline: v1.0.1

Status

ChessView is suitable for local development, diploma demonstration, and single-instance Docker Compose deployment. It is not described as a hardened industrial deployment: matchmaking queues, WebSocket rooms, and background game monitors are in memory, and uploaded media is stored locally.

Features

Implemented core:

• JWT registration, login, refresh, current-user loading, and guarded frontend routes
• player profiles, ratings, leaderboard, history, and head-to-head comparison
• live 1v1 chess with server-side move validation through python-chess
• time controls, clock snapshots, resign/draw flows, reconnect handling, timeout, and early auto-abort policy
• WebSocket endpoint at /ws?token=<access_token> with typed event envelopes
• game chat and WebRTC signaling relay for live games
• replay/review and local Stockfish analysis in the browser
• analysis workspace with FEN/PGN workflows and board editing
• puzzle catalog and per-user attempt tracking
• tournaments with Swiss helpers, standings, round progression, entry-payment emulator hooks, and OTB tournament type
• scheduled matches with invite/accept/decline/cancel/start lifecycle
• admin API and separate admin frontend for user, audit, payment, and verification views

Demo and extended modules:

• ClubsPage is a frontend demonstration module with local UI state.
• ShopPage is a marketplace/wallet UI demonstration. It reads profile coins and stores item inventory locally in the browser.
• payments are handled by an emulator for internal scenarios such as scheduled match or tournament entry payments.
• face verification and passkey flows provide a local architectural foundation, not a certified identity verification service.

Known limitations:

• single application instance is assumed
• matchmaking queue, WebSocket connection state, room membership, and game monitor are process-local
• media storage is local filesystem storage under backend/storage
• horizontal scaling would require Redis/pub-sub, distributed monitor coordination, and object storage
• WebSocket authentication uses a query token, which is practical for this local app but should be reviewed for hardened deployments
• automated E2E and load testing are not part of the current baseline

Tech Stack

• Frontend: React, TypeScript, Vite, TanStack Query, Zustand, react-router, react-chessboard, chess.js, Stockfish, Tailwind CSS
• Backend: FastAPI, SQLAlchemy async, Alembic, PostgreSQL, Uvicorn, PyJWT, python-chess
• Tooling: Docker Compose, Yarn Classic, uv, pytest, ESLint, TypeScript build

Repository Layout

backend/          FastAPI app, domains, migrations, tests
frontend/         React/Vite user frontend
admin-frontend/   React/Vite admin frontend
docs/             architecture, domain, event, scaling, diploma notes
docker-compose.yml
justfile

Useful docs:

• Architecture
• Domain map
• Event contract
• Scaling notes
• Backend README
• Frontend README

Environment

Create a local env file:

Copy-Item .env.example .env

The example file contains local development defaults. Replace JWT_SECRET and database credentials for any shared environment.

Important variables:

• DATABASE_URL: backend connection string for local split development
• DOCKER_DATABASE_URL: backend container connection string for Docker Compose
• STORAGE_DIR: local media directory for backend commands
• DOCKER_STORAGE_DIR: media directory inside the backend container
• VITE_SERVER_URL: browser-facing backend URL
• VITE_API_PROXY_TARGET, VITE_WS_PROXY_TARGET: Vite proxy targets

Quickstart: Docker Compose

docker compose up --build

Endpoints:

• frontend: http://localhost:5173
• admin frontend: http://localhost:5174
• backend health: http://localhost:8000/health
• backend API base: http://localhost:8000/api/v1

Check the resolved Compose configuration:

docker compose config

Quickstart: Split Development

Start PostgreSQL:

docker compose up -d postgres

Start backend:

cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --host localhost --port 8000

Start frontend:

cd frontend
yarn install --frozen-lockfile
yarn dev

Start admin frontend:

cd admin-frontend
yarn install --frozen-lockfile
yarn dev

Verification Commands

Backend:

cd backend
uv run python -m compileall app domains infrastructure shared tests
uv run alembic upgrade head
uv run alembic check
uv run python -c "import app.main"
uv run pytest tests

Frontend:

cd frontend
yarn install --frozen-lockfile
yarn lint
yarn test:ui-consistency
yarn build

Admin frontend:

cd admin-frontend
yarn install --frozen-lockfile
yarn typecheck
yarn build

Smoke checks after backend startup:

Invoke-RestMethod http://localhost:8000/health
try {
  Invoke-RestMethod http://localhost:8000/api/v1/puzzles
} catch {
  $_.Exception.Response.StatusCode.value__
}

The second command is expected to return 401 without an access token.

Troubleshooting

• uv is missing: install it from https://docs.astral.sh/uv/ or run backend checks through the existing virtual environment if present.
• Docker cannot reach PostgreSQL: run docker compose config, then verify .env has POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and DOCKER_DATABASE_URL.
• frontend API calls fail in dev: check VITE_API_PROXY_TARGET and VITE_WS_PROXY_TARGET.
• protected API returns 401: log in first and send Authorization: Bearer <access_token>.
• avatar upload fails: verify STORAGE_DIR exists and the file is PNG, JPEG, or WebP within backend limits.

CI

Pull request CI runs backend compile/migrations/tests, frontend lint/UI consistency/build, and admin frontend typecheck/build. Keep local commands aligned with .github/workflows/pr-ci.yml.