# Clone the repository
git clone https://github.com/frbelotto/FreeTimerAlert.git
cd FreeTimerAlert

# Install dependencies
uv sync

# Run with unified entry point
python -m src              # GUI interface (default)
python -m src --terminal   # Terminal interface

# GUI interface (default)
python -m src
python -m src --debug --mute

# Terminal interface
python -m src --terminal
python -m src --terminal --debug --mute

# Run GUI (default)
python -m src

# With options
python -m src --debug --mute

# Navigate to the dist folder
cd dist

# Run GUI (default)
./FreeTimer

# Run Terminal interface
./FreeTimer --terminal

# With debug logging
./FreeTimer --debug

# Run terminal interface
python -m src --terminal

# With options
python -m src --terminal --debug --mute

🎉 Welcome to FreeTimer!
▶️  create: Create timers (name, duration)
▶️  start: Start timer (name)
...

⌨️  Enter command: create
Enter value for 'name' (text): focus
⏰ Accepted time formats...
Enter value for 'duration' (time (90, 45m, 1h30m, 30s)): 25m

⌨️  Enter command: start
Enter value for 'name' (text): focus
🟢 Timer 'focus' started!
Time remaining: 0:24:59
...

# GUI interface (default)
python -m src
python -m src --debug --mute

# Terminal interface
python -m src --terminal
python -m src --terminal --debug --mute

# Legacy entry points (backward compatible)
python main.py --debug --mute

FreeTimer follows a clean layered architecture with clear separation of concerns:

### Core Components

#### **Timer** (`src/core/timer.py`)
- **Responsibility**: Self-contained timer with complete lifecycle management
- **Implementation**: Python dataclass with threading support
- **Manages**: duration, remaining time, status, and its own execution thread
- **Methods**: `start()`, `pause()`, `resume()`, `stop()`, `reset()`, `add_time()`
- **Thread-safe**: Uses locks for all state modifications

#### **TimerService** (`src/services/timer_service.py`)
- **Responsibility**: Coordinator for multiple named timers
- **Manages**: catalog of timers by name
- **Methods**: `create_timer()`, `start_timer()`, `stop_timer()`, `pause_or_resume_timer()`, `remove_timer()`
- **Delegates**: Forwards commands to individual timers

#### **Terminal Interface** (`src/interfaces/terminal/interface.py`)
- **Responsibility**: User interaction and command processing via CLI
- **Uses**: match/case statements for command routing
- **Configures**: Sound notification callbacks during timer creation

#### **GUI Interface** (`src/interfaces/gui/main_window.py`)
- **Responsibility**: Desktop graphical user interface using Tkinter
- **Components**: 
  - `MainWindow` - Main application window, toolbar, menu bar, and orchestration
  - `TimerWidget` (`timer_widget.py`) - Individual timer display with controls and status
  - `CreateTimerDialog` (`dialogs.py`) - Timer creation dialog with validation
  - `AboutDialog` (`dialogs.py`) - Application information dialog
  - `ReadMeDialog` (`dialogs.py`) - Built-in README viewer
- **Features**: 
  - Real-time updates with dynamic refresh rates (100-500ms)
  - Sound toggle for audio notifications
  - Scrollable timer list for unlimited timers
  - Cross-platform system notifications (via `system_notifications.py`)
  - Color-coded status indicators (green=running, yellow=paused, blue=finished)
- **Status**: ✅ Fully functional
- **Reuses**: Same `TimerService` and `Timer` core logic as terminal interface

#### **Notifications** (`src/interfaces/terminal/notifications.py`)
- **Functional module**: Uses simple functions instead of classes
- **Functions**: `play_start_sound()`, `play_end_sound()`
- **Handles**: Audio playback with graceful error handling

#### **System Notifications** (`src/services/system_notifications.py`)
- **Responsibility**: Cross-platform desktop/system notifications
- **Functions**: `show_notification()`, `show_timer_finished_notification()`
- **Platform support**: Windows (plyer), macOS (osascript), Linux (notify-send/plyer)
- **Graceful handling**: WSL detection, fallback mechanisms, silent failure
- **Used by**: GUI interface for timer completion alerts

### Architecture Diagram

```mermaid
flowchart TB
    subgraph UIs["🖥️ User Interfaces"]
        subgraph Terminal["Terminal CLI"]
            TermInt[Terminal Interface<br/>Command Processing<br/>match/case routing]
        end
        
        subgraph GUI["Desktop GUI (Tkinter)"]
            MainWin[MainWindow<br/>Orchestration<br/>Toolbar + Menu]
            TimerWid[TimerWidget<br/>Visual Display Only<br/>Fires Callbacks]
            Dialogs[Dialogs<br/>Create/About/ReadMe]
            MainWin -->|creates with callbacks| TimerWid
            MainWin -->|shows| Dialogs
            TimerWid -.->|button click callbacks| MainWin
        end
    end
    
    subgraph Service["⚙️ Service Layer"]
        TS[TimerService<br/>Timer Catalog<br/>Command Delegation]
    end
    
    subgraph Core["💾 Self-Contained Timers"]
        subgraph T1["Timer: work"]
            T1D[Data: 25min<br/>Status: RUNNING]
            T1T[Own thread]
        end
        subgraph T2["Timer: break"]
            T2D[Data: 5min<br/>Status: PAUSED]
            T2T[Own thread]
        end
    end
    
    subgraph Notify["🔔 Notifications"]
        NS[Sound Functions<br/>play_start_sound<br/>play_end_sound]
        SysNotif[System Notifications<br/>Desktop Alerts<br/>Cross-platform]
    end
    
    TermInt --> TS
    MainWin -->|commands| TS
    TS -->|delegates| T1
    TS -->|delegates| T2
    
    T1T -.->|internal tick| T1D
    T2T -.->|paused| T2D
    
    T1 -->|on_start/on_end| NS
    T2 -->|on_start/on_end| NS
    T1 -->|on_finish| SysNotif
    T2 -->|on_finish| SysNotif
    
    MainWin -.->|polls every 100-500ms| TS
    MainWin -.->|reads timer data| T1
    MainWin -.->|reads timer data| T2
    MainWin -.->|passes data to| TimerWid

# Run GUI interface (default)
python -m src
python -m src --debug --mute

# Run terminal interface
python -m src --terminal
python -m src --terminal --debug --mute

# Or using task runner
uv run task run              # GUI interface (default)
uv run task terminal         # Terminal interface

# Format code
uv run task format

# Run tests
uv run task test

# Run tests (fast - exclude slow and integration tests)
uv run task test-fast

# Run all tests with detailed output
uv run task test-all

# Run only build tests
uv run task test-build

# Install build dependencies
uv sync --group build

# Build executable (creates dist/FreeTimer or dist/FreeTimer.exe)
python build.py

# Or using task runner
uv run task build