Smart Pomodoro

Problem

Focus planning usually lives apart from the calendar, so planned study blocks and actual timer sessions drift apart. The product needed to respect calendar intent while keeping timer state local and recoverable.

Constraints

• Generated focus and break intervals must remain app-local
• Google Calendar access should stay read-only
• Timer runtime must survive background tab throttling and page refreshes
• OAuth tokens need encrypted server-side storage
• Planning logic should be shared and testable outside the UI

Key Decisions

1. Read-only Calendar integration

   The app needed calendar context without taking over the user's calendar or filling it with generated focus/break entries.

   Read selected focus calendar events and generate intervals inside the app instead of writing generated sessions back to Google Calendar.

   Trade-off: Calendar remains cleaner and safer, but focus-session completion data must live in the app database.
2. Timestamp-based timer over interval counting

   Browser timers can drift when tabs are backgrounded or the device sleeps.

   Calculate active session progress from timestamps and persisted session state rather than trusting every interval tick.

   Trade-off: Slightly more runtime state management, but recovery and completion behavior are much more reliable.
3. NestJS API over server-only Next routes

   The app has auth, calendar, sessions, presets, settings, and planning domains that benefit from backend module boundaries.

   Use NestJS with Drizzle/PostgreSQL as a separate API layer behind the Next frontend.

   Trade-off: More services to run locally, but cleaner domain boundaries and deployment flexibility.