Mental Model: Pomodoro Timer TUI in Python

Timers are a great way to learn state transitions and time-driven loops.

State Machine Mental Model

At any moment, the timer has:

phase (FOCUS or BREAK)
remaining seconds
running/paused status
completed focus sessions

Commands and ticks should only move between valid states.

Event Sources

This app reacts to two event types:

user events: start, pause, reset, quit
time events: one-second tick

Thinking in events makes control flow much easier to reason about.

Python-Specific Insight

Python’s dataclass + Enum combo is ideal here.

dataclass keeps mutable timer state compact
Enum makes phases explicit and typo-resistant
time.sleep(1) creates a simple ticker

You get clarity without framework overhead.

Transition Rules to Memorize

decrement only when running
on zero during focus: increment sessions, switch to break
on zero during break: switch to focus
reset restores current phase duration and pauses

If these rules are clean, the timer feels solid.

Debugging by Invariants

Watch these invariants:

remaining time should not drift far below zero
phase switch happens only at boundary
sessions increase only after focus completion

Invariants are your fast sanity checks.

Good Next Upgrades

long break every fourth focus session
auto-start next phase toggle
daily stats persisted to JSON

Add features by extending state + transition rules, not by sprinkling random conditionals.