Chess Study Tracker

A small local GUI app to track my chess studies and suggest what to study next.

Warning

This is a vibe-coded project. Use it at your own risk.

Stack

• Python 3.14
• PySide6 (Qt) for the GUI
• SQLite for local storage

Goals (initial)

• Simple local-first GUI
• Track study resources and sessions
• Suggest next study focus based on recent activity
• Keep the UI pleasant with light visual polish

Development Setup

Install dependencies with uv:

uv sync --group dev

Configure environment (optional Groq integration):

cp .env.example .env

Run the app:

uv run python -m app.main

Notes:

• The app applies pending database migrations automatically on startup.
• Set CHESS_STUDY_TRACKER_DB_PATH to override the default DB path (./data/chess_study_tracker.db).
• Set GROQ_API_KEY in .env to enable Groq summaries. If missing, local deterministic summaries are used.
• The app uses qt-themes with blender by default.
• Set CHESS_STUDY_TRACKER_QT_THEME to another available theme name (or empty to skip theme application).
• Set CHESS_STUDY_TRACKER_QT_STYLE to override Qt style (default: fusion).

Development Quality Gates

Run before committing:

uv run ruff check .
uv run ruff format .
uv run pytest

Documentation

• Product formulas and constants: docs/formulas.md
• Manual QA checklist: docs/manual_qa_checklist.md

UI Test Database

Create a simulated database for manual UI testing:

uv run python scripts/seed_test_db.py --overwrite

Launch app against the seeded DB:

CHESS_STUDY_TRACKER_DB_PATH=data/ui_test.db uv run python -m app.main