Skip to content

README_EN.md

Latest commit

ย 

History

History
306 lines (233 loc) ยท 8.12 KB

README_EN.md

File metadata and controls

306 lines (233 loc) ยท 8.12 KB
Raw

๐Ÿ‡ Ppodo

Grape-themed Pomodoro Timer - Pomodoro Timer with Gamification

A productivity tool that combines the Pomodoro Technique with grape harvesting gamification elements.

๐Ÿ“ Overview

Ppodo is a Windows desktop application where you earn grapes with each focus session, complete grape bunches and boxes, brew wine, and feel a sense of achievement through leveling up and collecting badges.

Core Concept

  • ๐Ÿ‡ Pomodoro + Grape = Ppodo
  • ๐Ÿ“ˆ Visualize focus time as "Grape Harvest & Wine Brewing"
  • ๐ŸŽฎ A productivity app that grows like an RPG game

โœจ Key Features

๐ŸŒ Multi-language Support (I18N)

  • ํ•œ๊ตญ์–ด (Korean) / English / ๆ—ฅๆœฌ่ชž (Japanese) support
  • Change language in settings
  • All UI elements automatically translated

๐Ÿ”ฅ Pomodoro Timer

  • 25 min focus / 5 min break auto-switch (customizable)
  • Start, pause, resume, stop functions
  • Automatic notifications on focus completion
  • Progress bar and state indicator
  • High DPI display support

๐Ÿ‡ Grape Harvest & Wine Brewing System

Grape Berry
  โ†“ Collect 10
Grape Bunch
  โ†“ Collect 10
Grape Box
  โ†“ Collect 10
Wine Bottle
  โ†“ Collect 10
Wine Crate
  • 1 Pomodoro completed = 1 Grape Berry earned
  • 4-stage evolution system (Grape Harvest โ†’ Wine Brewing)
  • All stages visualized in 2x2 grid layout
  • Today's grape berry statistics

๐Ÿ“ˆ Level & Experience System

  • 1 Grape Berry = 10 XP
  • Level up formula: 100 ร— (1.5^(N-1)) XP
  • Congratulatory message on level up
  • Track consecutive focus days
  • Record total focus time

๐Ÿ† Badge System (15 types)

Milestones

  • ๐ŸŒฑ First Step: Earn 1 grape berry
  • ๐Ÿ‡ First Bunch: Complete 1 grape bunch
  • ๐Ÿ“ฆ First Box: Complete 1 grape box
  • ๐Ÿท First Wine: Complete 1 wine bottle
  • ๐Ÿพ Wine Master: Complete 1 wine crate

Consistency

  • ๐Ÿ”ฅ Week Streak: 7 consecutive days of focus
  • ๐Ÿ’ช Persistent: 50 consecutive days of focus

Daily Achievement

  • โšก Focus King: 10 grapes in a day
  • ๐Ÿ‘‘ Monthly Master: Focus 25 days in a month

Collection

  • ๐Ÿ’ฏ Veteran: Earn 100 grape berries
  • ๐Ÿญ Grape Farm: Complete 10 grape boxes
  • ๐Ÿ† Legend: Earn 1000 grape berries

Time-based

  • ๐ŸŒ… Early Bird: Focus between 6-9 AM
  • ๐Ÿฆ‰ Night Owl: Focus after 10 PM

Level

  • โญ Level Master: Reach level 10

Tasks

  • โœ… Perfectionist: Complete 100 tasks

Time

  • โฐ Time Traveler: 100 hours total focus

๐Ÿ“ Task Management

  • Add, complete, delete tasks
  • Select task before starting focus
  • Completed task statistics
  • Task history with timestamps

๐Ÿ“Š Statistics Analysis

  • Weekly Report: Last 7 days focus time bar chart
  • Task Distribution: Today's time per task pie chart
  • Daily/total statistics display

๐ŸŽจ Premium Themes (5 types)

  • Nordic: Nordic calmness and intellectual atmosphere (Steel Blue)
  • Midnight: Deep night's silence and perfect immersion (Dark Slate)
  • Forest: Forest's phytoncide-like stability (Deep Green)
  • Lavender: Inspiring and sensual violet (Vivid Violet)
  • Cafe: Relaxed and warm focus at the cafe (Coffee Bean Brown)

๐Ÿ› ๏ธ Tech Stack

  • Language: Python 3.8+
  • UI Framework: PySide6 (Qt for Python)
  • Database: SQLite3
  • Charts: Matplotlib
  • Packaging: PyInstaller

๐Ÿ“ฆ Installation & Running

1. Install Dependencies

pip install -r requirements.txt

2. Run Application

python main.py

3. Build Executable (.exe)

pyinstaller --noconsole --onefile --name "Ppodo" main.py

Generated file: dist/Ppodo.exe

๐Ÿ“ Project Structure

Ppodo/
โ”œโ”€โ”€ main.py                      # Application entry point
โ”œโ”€โ”€ requirements.txt             # Dependencies list
โ”œโ”€โ”€ README.md                    # Project documentation (Korean)
โ”œโ”€โ”€ README_EN.md                 # Project documentation (English)
โ”œโ”€โ”€ core/                        # Business logic
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ timer.py                # Pomodoro timer logic
โ”‚   โ”œโ”€โ”€ database.py             # SQLite database management
โ”‚   โ”œโ”€โ”€ theme.py                # Theme system
โ”‚   โ””โ”€โ”€ i18n.py                 # Multi-language support system
โ””โ”€โ”€ ui/                          # UI layer
    โ”œโ”€โ”€ __init__.py
    โ”œโ”€โ”€ main_window.py          # Main window
    โ”œโ”€โ”€ mini_window.py          # Mini window
    โ”œโ”€โ”€ timer_widget.py         # Timer display
    โ”œโ”€โ”€ task_widget.py          # Task management
    โ”œโ”€โ”€ stats_widget.py         # Statistics charts
    โ”œโ”€โ”€ grape_widget.py         # Grape collection system
    โ”œโ”€โ”€ level_widget.py         # Level & experience
    โ”œโ”€โ”€ badge_widget.py         # Badge collection
    โ”œโ”€โ”€ history_widget.py       # Task history
    โ”œโ”€โ”€ settings_dialog.py      # Settings dialog
    โ””โ”€โ”€ styles/                 # Styling modules
        โ”œโ”€โ”€ __init__.py
        โ””โ”€โ”€ theme_styles.py     # Theme-based style utilities

๐ŸŽฏ How to Use

1. Register Tasks

  • Add new tasks in "๐Ÿ“ Tasks" tab
  • Select task to work on from the list

2. Start Focus

  • Click "โ–ถ Start" button
  • 25-minute timer starts automatically
  • Check progress with progress bar

3. Complete Focus

  • Automatic notification after 25 minutes
  • ๐Ÿ‡ Grape Berry +1 earned
  • ๐Ÿ’ซ Experience +10 XP earned
  • 5-minute break starts automatically

4. Check Statistics

  • View weekly focus time in "๐Ÿ“Š Stats" tab
  • Check time distribution per task

5. Collect Badges

  • View badge collection in "๐Ÿ† Badges" tab
  • Badges automatically awarded when conditions are met

๐ŸŽฎ Gamification Reward System

Immediate Rewards

  • โœ… Pomodoro completed โ†’ Grape Berry +1
  • โญ Experience +10 XP

Short-term Goals

  • ๐Ÿ‡ 10 Grape Berries โ†’ Grape Bunch completed
  • ๐Ÿ† 10 grapes in a day โ†’ "Focus King" badge

Mid-term Goals

  • ๐Ÿ“ฆ 10 Grape Bunches โ†’ Grape Box completed
  • ๐Ÿท 10 Grape Boxes โ†’ Wine Bottle completed
  • โญ Reach Level 5
  • ๐Ÿ”ฅ 7 consecutive days โ†’ "Week Streak" badge

Long-term Goals

  • ๐Ÿพ 10 Wine Bottles โ†’ Wine Crate completed (Final stage!)
  • โญ Reach Level 10 โ†’ "Level Master" badge
  • ๐Ÿ† 1000 Grape Berries โ†’ "Legend" badge
  • ๐ŸŽ–๏ธ Collect all 15 badges

๐Ÿ“Š Database Schema

Main Tables

  • tasks: Task management
  • focus_sessions: Focus session records
  • grape_stats: Daily grape berry statistics
  • user_profile: User level/experience/statistics
  • badge_definitions: Badge definitions (15 types)
  • user_badges: User earned badges

All data is stored in local SQLite database (ppodo.db).

๐Ÿš€ Future Development Plan

Phase 2 (Enhanced UX)

  • Grape berry earning animation effects
  • Level up celebration animation
  • Badge acquisition zoom effect
  • Sound effects (earning sound, level up sound)

Phase 3 (Advanced Features)

  • Monthly statistics and trend analysis
  • Custom notification sounds
  • Data export (CSV/JSON)
  • Seasonal limited badges
  • Challenge system

Phase 4 (Storage & Cloud Integration)

  • Multiple storage backend support
    • Local SQLite (default)
    • Notion Database integration
    • Supabase integration
  • Cloud synchronization
  • Data migration tool
  • Real-time backup feature

Phase 5 (Social Features)

  • Compare with friends
  • Weekly rankings
  • Share badges

๐Ÿ‘ค Developer

Dahae Julie Kim

๐Ÿ“„ License

This project is created for personal productivity enhancement.

๐Ÿ™ Acknowledgments

Thanks to Francesco Cirillo for creating the Pomodoro Technique.

Version: 2.2 Last Updated: 2026-01-03 Development Started: 2025-01-02

New Features (v2.2):

  • ๐Ÿท Wine brewing system added (4-stage evolution)
  • ๐Ÿ“ฆ Progress visualization with 2x2 grid layout
  • ๐Ÿ‡ Grape harvest โ†’ Wine bottle โ†’ Wine crate completion goal

Previous Update (v2.1):

  • ๐ŸŒ Multi-language support (Korean, English, Japanese)
  • ๐Ÿ“ฑ High DPI display optimization
  • ๐ŸŽจ Improved UI visibility

Focus, grow, harvest grapes, and brew wine! ๐Ÿ‡๐Ÿทโœจ