WordMatch

English documentation. Russian version: README_ru.md.

WordMatch is a learning full-stack word-search puzzle game project.

Implemented Features

• 50 levels (level_01 ... level_50) with ru/en themes.
• Grid sizes:
  • 1-10: 8x8
  • 11-29: 16x16
  • 30-40: 8x8
  • 41-50: 16x16
• Backend-first architecture:
  • auth/registration and sessions (JWT access/refresh);
  • progress, score, time, and level stats stored in SQLite;
  • leaderboards and aggregated stats handled on the backend.
• In-game hints:
  • cost 1000 points;
  • max 2 hints per level;
  • sounds for hints and highlighted suggested words.
• Level-complete and final modals:
  • 0..5 star rating;
  • star animations and sound;
  • final stats (score, time, hints, rating).
• UI sections:
  • Menu, Game Board, Profile, Leaderboard, Settings, Help.
• Profile:
  • avatar upload/delete;
  • username change with 200s cooldown.
• Leaderboard:
  • modes: overall, speed, mastery, by level;
  • periods: all-time, 30d, 7d;
  • pagination, current user highlight;
  • metric explanations, position trend, achievement badges.
• UI localization via Paraglide: ru/en.
• Audio via Howler with sprite.ogg audio sprite.
• Touch controls and mobile-friendly layout.
• Local network access for frontend and backend.

Stack

• Frontend: Svelte 5 (TypeScript) + Tailwind CSS 4 + Vite + @inlang/paraglide-js + Howler.js
• Backend: FastAPI + SQLModel + SQLAlchemy + Alembic + SQLite
• Tooling: bun (frontend), uv (backend)

Project Structure

• frontend/ - client application
• backend/ - API, database, business logic
• docs/ - project docs and plans
• start-dev.sh - starts backend and frontend together

Requirements

• Python >= 3.11
• uv
• bun

Installation

Backend

cd backend
uv sync

Frontend

cd frontend
bun install

Running

Quick start (recommended)

./start-dev.sh

The script starts both servers and prints local/LAN URLs.

Manual start

Backend (8000):

cd backend
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend (5173):

cd frontend
bun run dev --host 0.0.0.0 --port 5173

Main URLs

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000
• Swagger: http://localhost:8000/docs

Database

• The SQLite database is created automatically on backend startup if the DB file does not exist.
• Backend startup also runs leaderboard aggregate reconciliation for consistency.

Core API

• Auth:
  • POST /api/auth/register
  • POST /api/auth/login
  • POST /api/auth/refresh
  • POST /api/auth/logout
  • GET /api/auth/me
• Progress:
  • GET /api/me/progress
  • PUT /api/me/progress
  • POST /api/me/progress/reset
  • POST /api/me/level-complete
  • GET /api/me/level-runs
• Profile:
  • GET /api/me/profile
  • POST /api/me/avatar
  • DELETE /api/me/avatar
  • PUT /api/me/username
• Leaderboard:
  • GET /api/leaderboard
  • GET /api/leaderboard/levels/{level_number}
  • GET /api/leaderboard/me

Useful Commands

Frontend

cd frontend
bun run check
bun run build
bun run preview

Backend

cd backend
uv run alembic upgrade head
uv run python -m app.cli.reconcile_leaderboard

Additional Docs

• Detailed backend documentation (environment variables, CORS, migrations): backend/README.md