Build Pomodoro Timer web app

[ibuzzardo]

Overview

Build a Pomodoro Timer web application using Next.js 15 App Router. The app helps users manage work sessions using the Pomodoro Technique — 25-minute focused work intervals followed by 5-minute breaks. After 4 pomodoros, take a 15-minute long break.

Requirements

• Next.js 15 App Router with TypeScript (strict mode)
• Single-page application with a large countdown timer display
• Three timer modes: Focus (25 min), Short Break (5 min), Long Break (15 min)
• Start, Pause, Reset controls
• Visual progress indicator showing completed pomodoros (4 dots/circles)
• Auto-transition: after Focus → Short Break, after 4 Focus sessions → Long Break
• Sound notification when timer completes (use Web Audio API to generate a simple beep, no external audio files)
• Session counter showing total completed focus sessions today
• Dark theme with Tailwind CSS
• Keyboard shortcuts: Space = start/pause, R = reset, 1/2/3 = switch mode
• GET /api/health returns { status: "ok" }

File Structure

src/
├── app/
│   ├── layout.tsx          # Root layout with dark theme, Inter font
│   ├── page.tsx            # Main page — imports PomodoroTimer client component
│   ├── globals.css         # Tailwind base styles
│   └── api/
│       └── health/
│           └── route.ts    # Health check endpoint
├── components/
│   ├── PomodoroTimer.tsx   # 'use client' — main timer logic + display
│   ├── TimerDisplay.tsx    # Circular countdown display component
│   ├── TimerControls.tsx   # Start/Pause/Reset buttons
│   └── ProgressDots.tsx    # Shows completed pomodoro count (4 dots)
├── lib/
│   └── audio.ts            # Web Audio API beep sound generator
├── hooks/
│   └── useTimer.ts         # Custom hook: countdown logic, mode switching, session tracking
package.json
tsconfig.json
next.config.js
tailwind.config.ts
postcss.config.js
.gitignore

Dependencies

• next@15 — Framework
• react@19, react-dom@19 — UI
• typescript@5 — Types
• tailwindcss@3, postcss, autoprefixer — Styling

Acceptance Criteria

• npm install && npm run build succeeds with no errors
• Timer counts down from 25:00 in Focus mode
• Start/Pause/Reset buttons work correctly
• Timer auto-switches to Break mode when Focus completes
• After 4 focus sessions, switches to Long Break
• Progress dots fill in as pomodoros complete
• Beep sound plays when timer reaches 00:00
• Keyboard shortcuts work (Space, R, 1/2/3)
• Dark theme throughout
• GET /api/health returns { status: "ok" }
• Session counter increments on focus completion

Edge Cases

• Tab not focused — timer should still count (use setInterval, not requestAnimationFrame)
• Double-click start — should not create duplicate intervals
• Browser refresh — timer resets (no persistence needed)
• Audio context blocked — gracefully handle browsers that block autoplay