Pomodoro

A modern desktop Pomodoro timer built with Python and PySide6, designed to help users manage focused work sessions, breaks, and productivity history through a clean and customizable desktop interface.

✨ Features

• ⏱️ Focus and break timers
• ▶️ Start, pause, resume, and stop controls
• 🔄 Accurate timer state management
• 📊 Circular progress visualization
• 📝 Activity tracking for each session
• 📚 Session history
• ✏️ Edit recorded activities
• 🗑️ Delete individual sessions
• 🧹 Clear complete session history
• 💾 Persistent data storage with SQLite
• 🌐 Persian and English language support
• ↔️ RTL / LTR interface support
• 🌙 Dark and Light themes
• ⚙️ Customizable focus and break durations
• 🔔 Session completion notification and sound
• 🔢 Persian number formatting
• 🖥️ Native desktop application with Qt Widgets

🖼️ Screenshots

Main Interface

Settings

Timer and Session Management

Application Interface

Session History

🛠️ Tech Stack

• Python
• PySide6
• Qt Widgets
• SQLite
• QTimer
• QSS
• Object-Oriented Programming
• Modular Application Architecture

🏗️ Project Structure

Pomodoro/
│
├── assets/
│   ├── fonts
│   ├── bell.mp3
│   └── application icons
│
├── images/
│   ├── 1.JPG
│   ├── 2.JPG
│   ├── 3.JPG
│   ├── 4.JPG
│   ├── 5.JPG
│   └── ...
│
├── app.py
├── config.py
├── database.py
├── main.py
├── timer.py
├── widgets.py
├── requirements.txt
└── .gitignore

Core Modules

File	Responsibility
main.py	Application entry point
app.py	Main application logic and UI integration
timer.py	Timer engine and session state management
database.py	SQLite database management
config.py	Configuration, translations, paths, and helper functions
widgets.py	Custom UI widgets and interface components

💾 Data Persistence

The application uses SQLite to persist application settings and session history.

The database stores:

• Application settings
• Focus duration
• Break duration
• Selected language
• Selected theme
• Session date
• Start time
• End time
• Session duration
• Activity
• Session type
• Completion status

The database is created automatically next to the application:

pomodoro.db

This means your settings and productivity history remain available after restarting the application.

🌍 Internationalization

Pomodoro supports both:

• 🇮🇷 Persian
• 🇬🇧 English

The interface automatically adapts to the selected language, including:

• Text translations
• RTL / LTR layout
• Number formatting
• Timer display
• Session history

The default configuration is Persian with a dark theme.

🎨 Customization

Users can customize:

• Focus duration
• Break duration
• Application language
• Application theme

Default configuration:

Language: Persian
Theme: Dark
Focus: 25 minutes
Break: 5 minutes

🚀 Installation

1. Clone the repository

git clone https://github.com/AliValizade/Pomodoro.git

2. Navigate to the project

cd Pomodoro

3. Create a virtual environment

Windows:

python -m venv .venv

Activate it:

.venv\Scripts\activate

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate

4. Install dependencies

pip install -r requirements.txt

5. Run the application

python main.py

▶️ Usage

1. Launch the application.
2. Enter the activity you want to work on.
3. Start a focus session.
4. Pause or resume the timer when necessary.
5. Complete or stop the session.
6. Review your session history.
7. Adjust language, theme, focus duration, and break duration from Settings.

🧠 Architecture

The application follows a modular structure that separates:

• UI components
• Application logic
• Timer engine
• Database operations
• Configuration and localization

This structure makes the project easier to maintain, extend, and experiment with.

🔮 Roadmap

Possible future improvements include:

• Automatic focus → break transitions
• Productivity statistics and charts
• Daily and weekly reports
• Custom notification sounds
• More advanced session analytics
• Exporting productivity data
• Additional themes
• Application packaging for Windows
• Improved desktop notifications

📌 Project Status

Status: Active Development

Pomodoro is a personal desktop productivity application and an ongoing Python/PySide6 project focused on practical desktop software development.

🎯 Learning Goals

This project was developed to practice and demonstrate:

• Python application architecture
• PySide6 / Qt Widgets
• GUI development
• Event-driven programming
• Timer management
• SQLite database integration
• Data persistence
• Localization and internationalization
• RTL / LTR interface design
• Modular software design

📄 License

This project is currently provided for educational and personal use.

See the repository for the latest source code and updates.

---

👨‍💻 Author

Ali Valizadeh

Python Developer | AI & Automation Engineer | Django | University Instructor

• GitHub: AliValizade
• LinkedIn: Ali Valizadeh

---

⭐ If you find this project useful or interesting, consider giving it a star.