CPTracker Tkinter Pygame

CP Tracker Arena is a Python desktop application that combines a Codeforces progress dashboard with an algorithm games arena.
It was built to help competitive programming learners track their Codeforces journey, organize practice problems, follow upcoming contests, and learn algorithms through interactive games.

The project contains two big parts:

1. CP Tracker — a modern CustomTkinter dashboard connected to the Codeforces API.
2. CP Arena — a Pygame-based learning area with algorithm games:
   • Tower of Hanoi — recursion, stacks, and optimal-move thinking.
   • Pathfinder Arena — shortest path visualization on a grid.

Note: the Pathfinder game in this version uses BFS for shortest path search on an unweighted grid. Since every move has the same cost, BFS gives the same shortest path result as Dijkstra with unit weights. A future version can extend it to weighted cells and a full Dijkstra implementation.

---

Preview

Add screenshots after pushing the project:

/docs/screenshots/login.png
/docs/screenshots/dashboard.png
/docs/screenshots/cp-arena.png
/docs/screenshots/hanoi.png
/docs/screenshots/pathfinder.png

Example Markdown after adding screenshots:

![Dashboard](docs/screenshots/dashboard.png)
![CP Arena](docs/screenshots/cp-arena.png)

---

Main Features

Codeforces Dashboard

• Codeforces handle verification before entering the app.
• User profile display using the Codeforces API.
• Rating, rank, maximum rating, contribution, avatar, and last-online information.
• Rating history chart using Matplotlib.
• Solved problems analysis.
• Problems grouped by tags and ratings.
• Upcoming Codeforces contests with live countdown.
• Personal contest history management.
• To-do problem list with title, contest ID, index, tags, rating, and problem link.
• CSV export for saved problems.
• Dark modern UI with sidebar navigation.

CP Arena

• Dedicated game hub inside the desktop app.
• Launches algorithm games directly from the dashboard.
• Built with Pygame and separated game modules.
• Designed to make algorithm learning more visual and fun.

Tower of Hanoi Game

• Interactive drag-and-drop Tower of Hanoi.
• Supports changing the number of disks.
• Enforces valid moves only.
• Tracks number of moves.
• Shows the theoretical minimum moves.
• Detects perfect win vs normal win.
• Reset and replay controls.
• Neon/cyberpunk visual design.

Pathfinder Arena

• Interactive grid-based shortest path game.
• Easy and Advanced levels.
• Obstacles, start cell, target cell, timer, and step tracking.
• Player must move one cell at a time.
• Hint system.
• BFS visualization showing visited nodes.
• Optimal path comparison.
• Result screen based on path quality.
• Code view screen for learning the algorithm.
• Animated UI with particles, glow effects, and responsive resizing.

---

Tech Stack

Area	Technologies
Desktop UI	Python, CustomTkinter
Codeforces API	Requests
Charts	Matplotlib
Images	Pillow
Games	Pygame
Database	MySQL
Data export	CSV

---

Project Structure

CPtracker/
│
├── main.py                         # Main entry point for the desktop app
├── api_codeforces.py               # Codeforces API helper functions
├── config.py                       # Configuration file
├── requirements.txt                # Python dependencies
├── database_schema.sql             # MySQL schema for local setup
│
├── assets/
│   └── logo_Cp_tracker.png         # Application logo
│
├── db/
│   ├── __init__.py
│   └── database.py                 # MySQL connection and table creation
│
├── ui/
│   ├── __init__.py
│   ├── login.py                    # Login screen and Codeforces handle validation
│   ├── dashboard.py                # Main dashboard, sidebar, charts, statistics
│   ├── profile.py                  # Codeforces profile page
│   ├── contests.py                 # Upcoming contests and contest history
│   ├── solved.py                   # Accepted submissions / solved problems
│   ├── todo.py                     # Personal problem todo list
│   └── cp_arena.py                 # Algorithm games hub
│
├── games/
│   ├── __init__.py
│   │
│   ├── hanoi/
│   │   ├── main.py                 # Tower of Hanoi game entry point
│   │   ├── settings.py             # Hanoi constants and colors
│   │   ├── assets/
│   │   │   ├── images/             # Hanoi background and tower images
│   │   │   └── sounds/             # Optional game music
│   │   ├── game/
│   │   │   ├── state.py            # Hanoi game state and rules
│   │   │   ├── input_handler.py    # Mouse interactions and controls
│   │   │   ├── renderer.py         # Drawing logic and win screens
│   │   │   ├── create_tower.py     # Tower helper logic
│   │   │   └── ui.py               # Reserved UI helper file
│   │   └── utils/
│   │       └── helpers.py          # Utility helpers
│   │
│   └── pathfinder/
│       ├── main.py                 # Pathfinder game entry point
│       ├── constants.py            # Colors, levels, UI constants, BFS code snippet
│       ├── grid.py                 # Grid model and BFS shortest path logic
│       ├── game.py                 # Game states, player movement, rendering flow
│       ├── ui.py                   # Buttons, particles, panels, flash messages
│       ├── pyperclip_fallback.py   # Clipboard fallback helper
│       ├── interstellar.mp3        # Optional background music
│       └── gameover.mp3            # Optional result music
│
└── docs/
    └── screenshots/                # Screenshots for the README

---

Detailed Project Explanation

main.py

This is the application entry point. It starts the CustomTkinter application by creating the login screen:

from ui.login import LoginApp

app = LoginApp()
app.run()

The user does not directly enter the dashboard. First, the app asks for a Codeforces handle and validates it using the Codeforces API.

---

api_codeforces.py

This file centralizes all Codeforces API calls.

Main functions:

• check_handle_exists(handle)
  Checks whether a Codeforces handle exists.

• get_full_user_info(handle)
  Gets profile information such as handle, rank, rating, max rating, contribution, avatar, and last online timestamp.

• get_user_contests(handle)
  Gets the user's Codeforces rating history.

• get_upcoming_contests()
  Gets upcoming contests from contest.list and keeps contests with phase BEFORE.

• get_solved_problems(handle)
  Reads user submissions, keeps only OK verdicts, removes duplicates, and returns solved problem data.

• get_rating_history(handle)
  Returns the user's rating updates for the rating progress chart.

This separation makes the UI cleaner because API logic stays in one file.

---

db/database.py

This file manages the MySQL connection.

It connects to a local database named:

cptracker

It creates two main tables:

1. todo — stores saved practice problems.
2. contest_history — stores personal contest results.

The current default connection uses:

host: localhost
user: root
password: empty

This is common for local XAMPP/MySQL development.

---

UI Layer

ui/login.py

This file builds the first screen of the app.

Responsibilities:

• Shows the CP Tracker logo.
• Displays a welcome message.
• Shows an input for the Codeforces handle.
• Validates the handle with check_handle_exists().
• Opens the main dashboard if the handle is valid.
• Shows an error if the handle does not exist.

The login screen protects the app from loading empty or invalid Codeforces data.

---

ui/dashboard.py

This is the main page controller of the desktop app.

Responsibilities:

• Builds the topbar and sidebar navigation.
• Shows the main dashboard page.
• Switches between pages:
  • Dashboard
  • Profile
  • Contests
  • CP Arena
  • Solved Problems
  • To Do Problems
• Loads Codeforces statistics.
• Creates Matplotlib charts.
• Shows problem tag concentration.
• Shows rating distribution.
• Shows rating progress history.
• Handles logout and sidebar collapse.

Dashboard analytics include:

• Solved problem count.
• Current rating.
• Maximum rating.
• Most common solved-problem tag.
• Most frequent rating bucket.
• Rating progress chart.
• Rating distribution chart.
• Tag concentration chart.

---

ui/profile.py

The profile page displays Codeforces account information.

Main elements:

• Avatar image.
• Handle.
• Current rank.
• Current rating.
• Maximum rating.
• Maximum rank.
• Contribution.
• Last online status.
• Recent rated contests.

It also colors ranks depending on Codeforces rank style, for example:

• Newbie: gray.
• Pupil: green.
• Specialist: blue/cyan.
• Expert: purple.
• Candidate Master: orange.
• Master/Grandmaster: red.

---

ui/contests.py

This page has two parts.

Upcoming Codeforces contests

The app loads upcoming Codeforces contests and displays:

• Contest name.
• Start time.
• Duration.
• Phase.
• Live countdown.

Countdown colors:

• Green: contest is still far.
• Orange: less than 24 hours.
• Red: less than 1 hour.

Personal contest history

The user can save personal contest results:

• Contest name.
• Rank.
• Total participants.
• Organization.

The page supports:

• Add contest.
• Edit contest.
• Delete contest.

---

ui/solved.py

This page shows solved Codeforces problems.

It uses accepted submissions from Codeforces and displays:

• Problem name.
• Contest ID and index.
• Rating.
• Tags.
• Solved date.
• Accepted status.

The page helps the user review what they have already solved.

---

ui/todo.py

This page is a personal training list for problems the user wants to solve later.

Each saved problem contains:

• Title.
• Contest ID.
• Problem index.
• Tags.
• Rating.
• Link.

Supported actions:

• Add problem.
• Edit problem.
• Delete problem.
• Open problem link in browser.
• Export the list to CSV.

It also includes predefined Codeforces tags and rating values to make problem organization faster.

---

ui/cp_arena.py

This page connects the dashboard to the game modules.

It shows game cards:

• Pathfinder
• Hanoi
• Future Game 3
• Future Game 4

When the user clicks a game card, it launches the corresponding Pygame script using subprocess.Popen() and the current Python interpreter.

This makes the CP Arena independent from the CustomTkinter UI while still being accessible from the dashboard.

---

Game 1: Tower of Hanoi

Location:

games/hanoi/

Goal

Move all disks from the first tower to the final tower while respecting the classic rule:

A larger disk cannot be placed on top of a smaller disk.

Algorithmic concepts

• Recursion.
• Stack behavior.
• State management.
• Minimum number of moves.
• Problem decomposition.

The minimum number of moves is:

2^n - 1

where n is the number of disks.

Main files

games/hanoi/main.py

Starts the Pygame window, loads optional music, creates the renderer, input handler, and game state, then runs the main game loop.

games/hanoi/settings.py

Contains constants:

• Window width and height.
• FPS.
• Game title.
• Minimum and maximum disk count.
• Default disk count.
• Colors.

games/hanoi/game/state.py

Stores the full game state:

• Towers.
• Number of disks.
• Move count.
• Dragging disk.
• Win status.

It also contains the core game rules:

• Only top disks can be moved.
• A disk can be dropped only on an empty tower or a larger disk.
• Win is detected when all disks reach the final tower.
• Perfect win is detected when moves equal 2^n - 1.

games/hanoi/game/input_handler.py

Handles mouse input:

• Selecting disks.
• Dragging disks.
• Dropping disks.
• Reset button.
• Disk count controls.
• Replay after win.

It connects the player's actions to the game state.

games/hanoi/game/renderer.py

Responsible for all drawing:

• Background.
• Towers.
• Disks.
• Move counter.
• Minimum move counter.
• Disk controls.
• Reset button.
• Perfect win screen.
• Normal win screen.

It gives the game its neon visual identity.

---

Game 2: Pathfinder Arena

Location:

games/pathfinder/

Goal

The player must move from the start cell to the target cell while avoiding obstacles and trying to match the optimal shortest path.

Algorithmic concepts

• Graphs.
• Grid representation.
• Breadth-First Search.
• Shortest path in unweighted graphs.
• Visited nodes.
• Path reconstruction.
• Complexity visualization.

Main files

games/pathfinder/main.py

Starts the Pygame window and runs the main game loop.

games/pathfinder/constants.py

Contains:

• Colors.
• UI sizes.
• Animation speed.
• Level definitions.
• Obstacles.
• Start/end cells.
• Timer values.
• BFS code snippet shown inside the game.

The project currently has two levels:

• Easy.
• Advanced.

games/pathfinder/grid.py

Represents the grid and implements the BFS algorithm.

Main methods:

• in_bounds(r, c) — checks if a cell is inside the grid.
• is_obstacle(r, c) — checks if a cell is blocked.
• neighbors(r, c) — returns valid neighboring cells.
• bfs() — returns the shortest path, visited order, and parent map.
• bfs_path_only() — returns only the shortest path.

games/pathfinder/game.py

Controls the full game behavior.

It manages states:

• Menu.
• Play.
• BFS visualization.
• Result.
• Code view.

It handles:

• Level selection.
• Player movement.
• Timer.
• Step counting.
• Hint logic.
• BFS animation.
• Result evaluation.
• Menu navigation.
• Music handling.

games/pathfinder/ui.py

Contains reusable UI components:

• Buttons.
• Particles.
• Flash messages.
• Panels.
• Glow effects.
• Text rendering helpers.

This keeps the game code cleaner and separates UI drawing helpers from the main logic.

games/pathfinder/pyperclip_fallback.py

Provides fallback clipboard support for copying the algorithm code when external clipboard tools are unavailable.

---

Database Setup

This project uses MySQL for local saved data.

Option 1: Use the included SQL file

Open MySQL or phpMyAdmin and run:

SOURCE database_schema.sql;

Or copy the content of database_schema.sql into phpMyAdmin SQL tab.

Option 2: Create tables from Python

Make sure MySQL is running and then execute:

python -c "from db.database import create_table; create_table()"

Default database settings are in db/database.py:

host="localhost"
user="root"
password=""
database="cptracker"

If your MySQL uses another port, username, or password, update db/database.py.

---

Installation

1. Clone the repository

git clone https://github.com/IDMen/cp-tracker-arena.git
cd cp-tracker-arena

2. Create a virtual environment

Windows PowerShell:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Set up MySQL database

Create the database and tables:

CREATE DATABASE cptracker;

Then run database_schema.sql or use:

python -c "from db.database import create_table; create_table()"

5. Run the app

python main.py

---

Running Games Directly

You can also run the games without opening the main dashboard.

Tower of Hanoi

python games/hanoi/main.py

Pathfinder Arena

python games/pathfinder/main.py

---

GitHub Push Preparation

Before pushing, make sure these files are not included:

venv/
__pycache__/
*.pyc
*.db
*.sqlite3
.vscode/
.idea/

This repository already includes a .gitignore file for that.

Also verify that you own or have permission to publish any music/images included in the assets folders. If not, replace them with royalty-free assets before making the repository public.

---

Suggested Repository Info

Repository name

cp-tracker-arena

or:

codeforces-cp-tracker-arena

Description

Python desktop app for tracking Codeforces progress with CustomTkinter, plus Pygame algorithm games for Tower of Hanoi and shortest path visualization.

Topics

python
customtkinter
pygame
codeforces
competitive-programming
algorithm-visualizer
pathfinding
breadth-first-search
tower-of-hanoi
matplotlib
mysql

---

Future Improvements

• Add a full Dijkstra mode with weighted cells.
• Add A* pathfinding visualization.
• Add more algorithm games to CP Arena.
• Package the project as an .exe using PyInstaller.
• Add authentication and local user profiles.
• Add offline caching for Codeforces data.
• Improve database configuration using environment variables.
• Add screenshots and a short demo video.
• Add unit tests for API and algorithm logic.

---

Author

Mohamed Azzouz
Competitive Programming & Software Development Enthusiast

• Codeforces: IDMen
• GitHub: IDMen
• LinkedIn: mohamed-azzouz-774055267

---

Acknowledgment

This project was built as a personal learning project to combine competitive programming tracking, algorithm visualization, and game-based learning in one desktop application.