Kotlin/JS Interactive Pomodoro Timer Web App

Project roadmap

1. 01

   Set up the Kotlin/JS project

   ~1.5h

   Create a Gradle project with the Kotlin Multiplatform plugin and a js target with browser { } and binaries.executable(). Add kotlinx-html. Write an index.html in resources with a root element, and a main function that writes Hello into it. Run it with ./gradlew jsBrowserDevelopmentRun. Done when: the page opens in the browser and shows the text from Kotlin.

2. 02

   Model the timer as a state machine

   ~1.5h

   Write plain Kotlin classes for the timer: the phase (work, short break, long break), the status (idle, running, paused), the end time while running and the remaining time while paused, and the completed session count. Write functions for start, pause, resume, skip and reset, and for moving to the next phase, which choose a long break after every 4th session. Done when: unit tests (with kotlin.test) show the phases change correctly.

3. 03

   Build the interface

   ~2h

   Render the timer with kotlinx.html: the remaining time as mm:ss in large text, the current phase with its color, the session count, and the buttons. Update the display with window.setInterval about 4 times a second, computing the remaining time from the end time and Date.now(), so it stays right even when the browser slows timers. Also show the time in the page title. Done when: the timer counts down smoothly and accurately, and the buttons work.

4. 04

   Add notifications and sound

   ~1.5h

   When a phase ends, play a short sound with the browser's Audio API and show a notification with the Notification API, asking for permission when the user first starts the timer. If permission is denied, show an in-page message instead. Then start the next phase automatically or wait, depending on a setting. Done when: finishing a session plays a sound and shows a notification, even in a background tab.

5. 05

   Save settings and history

   ~1.5h

   Save completed sessions (start, end and phase) and settings (durations and auto-start) in localStorage as JSON (with kotlinx.serialization), and show today's history with the total focus time. Restore a running timer after reloading the page from its saved end time. Handle missing or broken saved data by starting fresh. Done when: the history and settings survive a reload, and a running timer continues correctly.

6. 06

   Test and build

   ~1h

   Run the unit tests for the state machine and history functions with ./gradlew jsTest (in a headless browser). Build the production version with jsBrowserDistribution and open it from a simple static server. Done when: the tests pass, and the built app works.

Resources

• DocsKotlin/JS: get started
• DocsKotlin/JS: using browser and DOM APIs
• Docskotlinx.html
• DocsMDN: using the Notifications API
• ArticlePomodoro Technique (Wikipedia)