# otonar/pomodoro_timer architecture

> Architecture diagram of the GitHub repository otonar/pomodoro_timer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/otonar/pomodoro_timer
- Repository: https://github.com/otonar/pomodoro_timer

## Overview

Pomodoro is a Windows desktop timer. The main workflow is user controls → timer countdown → work/break cycle, with progress shown in the main window and optional HUD, tray, and taskbar integrations. The README documents global shortcuts and automatic session changes; excerpts show timer, HUD, tray, and Windows API implementation details. The single source file is only partially excerpted, so links between initialization and some integrations are left unverified rather than inferred.

Main entry points: [`pomodoro.py`](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py) (Main timer window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_timer["Timer lifecycle"]
  node_countdown["Countdown<br/>[pomodoro.py]"]
  node_session["Session cycling<br/>[pomodoro.py]"]
end

subgraph group_display["User interfaces"]
  node_keyboard["Global shortcuts<br/>[pomodoro.py]"]
  node_app["Main timer window<br/>[pomodoro.py]"]
  node_hud["Floating HUD<br/>[pomodoro.py]"]
end

subgraph group_integrations["Windows integrations"]
  node_tray["System tray<br/>[pomodoro.py]"]
  node_taskbar["Taskbar progress<br/>[pomodoro.py]"]
end

node_user(("User"))
node_windows["Windows APIs"]

node_user -->|"uses"| node_app
node_user -->|"presses shortcuts"| node_keyboard
node_keyboard -.->|"controls"| node_app
node_app -->|"starts or pauses"| node_countdown
node_countdown -->|"completes session"| node_session
node_session -->|"selects next interval"| node_countdown
node_app -->|"renders progress"| node_app
node_app -.->|"updates display"| node_hud
node_user -->|"uses controls"| node_hud
node_app -.->|"starts tray icon"| node_tray
node_tray -->|"dispatches actions"| node_app
node_app -.->|"updates progress"| node_taskbar
node_taskbar -->|"calls taskbar API"| node_windows

click node_keyboard "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_app "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_hud "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_countdown "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_session "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_tray "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"
click node_taskbar "https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_countdown,node_session,node_user toneBlue
class node_keyboard,node_app,node_hud toneAmber
class node_tray,node_taskbar,node_windows toneMint
```

## Components

### Timer lifecycle

- [Countdown](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`
- [Session cycling](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`

### User interfaces

- [Global shortcuts](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`
- [Main timer window](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`
- [Floating HUD](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`

### Windows integrations

- [System tray](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`
- [Taskbar progress](https://github.com/otonar/pomodoro_timer/blob/master/pomodoro.py): `pomodoro.py`

### Other components

- **User**
- **Windows APIs**

## Connections

- User → Main timer window: uses (evidence: `README.md`)
- User → Global shortcuts: presses shortcuts (evidence: `README.md`)
- Global shortcuts → Main timer window: controls (evidence: `pomodoro.py`)
- Main timer window → Countdown: starts or pauses (evidence: `pomodoro.py`)
- Countdown → Session cycling: completes session (evidence: `README.md`)
- Session cycling → Countdown: selects next interval (evidence: `README.md`)
- Main timer window → Main timer window: renders progress (evidence: `pomodoro.py`)
- Main timer window → Floating HUD: updates display (evidence: `pomodoro.py`)
- User → Floating HUD: uses controls (evidence: `pomodoro.py`)
- Main timer window → System tray: starts tray icon (evidence: `pomodoro.py`)
- System tray → Main timer window: dispatches actions (evidence: `pomodoro.py`)
- Main timer window → Taskbar progress: updates progress (evidence: `pomodoro.py`)
- Taskbar progress → Windows APIs: calls taskbar API (evidence: `pomodoro.py`)