Instruction file imported from zefirior/tastify (.cursor/rules/project-overview.mdc). Copyright stays with the author.

Tastify Project Overview

Purpose

Tastify is a collaborative multiplayer game platform for sharing music tastes. Players join rooms, play various games, and earn points.

The platform supports multiple games through a pluggable architecture. Each game has its own logic, API routes, and configuration.

Current Games:

• Guess the Number (default) - Players guess a randomly generated number (1-100). Closest guess wins.

Project Structure

/back                    - FastAPI backend (Python 3.12+)
  games.yaml             - Game configuration (enabled games, defaults, settings)
  /src
    /api                 - Legacy REST and WebSocket endpoints
    /games               - Game implementations (pluggable architecture)
      /base.py           - BaseGame abstract class
      /registry.py       - GameRegistry for managing games
      /router.py         - Generic game router factory
      /guess_number/     - Guess the Number game implementation
        /jobs/           - Game-specific background jobs (timer, etc.)
    /models              - SQLAlchemy ORM models
    /schemas             - Pydantic request/response schemas
    /services            - Business logic layer
    /jobs                - General background jobs (room cleanup, etc.)
    /db                  - Database configuration
  /migrations            - Alembic database migrations
  /tests                 - pytest tests with testcontainers

/front                   - React frontend (TypeScript)
  /src
    /api                 - API client and WebSocket client
    /stores              - MobX state management
    /pages               - Page components (Home, Lobby, Game, Results)
    /types               - TypeScript type definitions
  /tests                 - Playwright E2E tests

/docker                  - Docker Compose configurations
  docker-compose.yaml    - Local development (all services)
  remote.docker-compose.yaml - Production deployment

/scripts                 - Utility bash scripts
  common.sh              - Shared utilities (colors, logging, paths)
  run-tests.sh           - Test runner for backend and frontend

API Structure

Games API (New)

The new games API uses a unified structure for all games:

Legacy API

The legacy API (/api/rooms/...) is preserved for backward compatibility but uses the default game type.

Running the Project

Full Stack (Recommended)

Start all services with Docker Compose:

docker compose -f docker/docker-compose.yaml up --build

• Frontend: http://localhost:5173
• Backend: http://localhost:8000
• API Docs: http://localhost:8000/docs
• PostgreSQL: localhost:5432

Manual Setup

1. Start database only:

   docker compose -f docker/docker-compose.yaml up postgres -d

2. Backend:

   cd back
   uv sync
   uv run alembic upgrade head
   uv run uvicorn src.main:app --reload

3. Frontend:

   cd front
   npm install
   npm run dev

Running Tests

Prerequisites: Docker must be running (backend tests use testcontainers for PostgreSQL).

All Tests

./scripts/run-tests.sh

Backend Only

./scripts/run-tests.sh --backend-only

# Or directly:
cd back
uv sync --all-extras  # Install dev dependencies (pytest, testcontainers, etc.)
uv run pytest -v

Frontend Only

./scripts/run-tests.sh --frontend-only

E2E Tests (Playwright)

./scripts/run-tests.sh --e2e

# Or directly:
cd front && npm run test

Running Specific Tests

# Run a specific test file
cd back && uv run pytest tests/test_game_registry.py -v

# Run a specific test
cd back && uv run pytest "tests/test_games_api.py::TestExecuteAction::test_start_game_action" -v

Key Technologies

• Backend: FastAPI, SQLAlchemy (async), asyncpg, Alembic, Pydantic, PyYAML
• Frontend: React 19, Vite, MobX, TailwindCSS v4
• Database: PostgreSQL 16
• Testing: pytest + testcontainers (backend), Playwright (frontend)
• Real-time: WebSocket for live game updates