KodaPomo

The original brief was small and honest: an online Pomodoro app. Not a task platform, not a habit tracker — a place where the Pomodoro technique is literal. Twenty-five minutes of focus, five minutes of rest, a longer break after four sessions. The point was compartmentalisation: a user should be able to take one piece of work, break it into sessions they can actually finish, and see their effort managed instead of guessed at.

The first version was a generated Next.js timer: one mode, one countdown, no persistence. It worked, and it was not a product. From there the scope moved deliberately: stores instead of one component, tasks bound to sessions, ambient audio, analytics, then an AI planner and AI insights, then accounts, sync and billing. Each step was added because the previous one exposed a gap, not because the feature list looked short.

• v0.1.0 — generated Pomodoro UI, no persistence, no tasks.
• v0.2.0 — architecture overhaul: composition root plus independent stores for timer, tasks, settings, statistics and interface.
• Tasks — estimates, an active task bound to each session, per-session attribution, soft-delete archive.
• Audio — five mixable ambient channels, later a licensed music library served from private storage.
• Analytics — streaks, weekly minutes, peak hours, estimate accuracy, and a deterministic rule-based coaching layer.
• AI — planner (goal → preflight → blocks → tasks → subtasks) and insights over completed sessions.
• Platform — Supabase auth, per-identity sync, Stripe on web, RevenueCat on device, Capacitor wrapper for Android.

The 25/5 baseline is still the default. Discipline presets re-pace it — programming runs 50/10/20 — but the model behind it is identical, so a different rhythm never means a different code path.

• app/page.tsx is the composition root: it wires stores to components and owns the timer lifecycle.
• features/ holds vertical slices — the timer (store, hooks, notifications) and the AI feature (prompts, schemas, validators, rate limiting).
• store/ holds the seven Zustand stores, each with its own persistence key, version and migration path.
• lib/ holds cross-cutting concerns: audio, sync, Supabase clients, auth guards, origin checks, insights rules and the AI transport helpers.
• app/api/ is the entire server surface — AI routes, Stripe and RevenueCat webhooks, subscription status, account deletion, signed track delivery.
• supabase/migrations/ holds nine append-only migrations; every user table has RLS enabled and forced.

A Pomodoro timer is a correctness problem disguised as a UI problem. Browsers throttle background tabs, phones suspend WebViews, and users switch tabs for twenty minutes. Any timer that counts intervals will drift, and a productivity tool that lies about time is worse than no tool at all.

• Starting a session records an absolute end time; every repaint re-derives the remaining time from the wall clock instead of decrementing a counter.
• A 250 ms interval is only a repaint cadence — dropping frames or throttling changes nothing about the result.
• A visibility listener forces an immediate reconcile when the tab returns, and rehydration recomputes from the recorded start time so a reload cannot shorten or lengthen a session.
• Completion fires once, through a one-shot signal keyed by mode and start time, so React re-renders and Strict Mode cannot double-record.
• A broadcast channel elects a leader tab; follower tabs stand down instead of running competing timers.
• On Android, a native local notification is scheduled on the system clock when the session starts, so completion survives the WebView being suspended.

The database question was the one that mattered most: a productivity app can accumulate an unbounded amount of trivia, and every table added is a migration, an index and a sync path to maintain. The rule I settled on is simple — persist what a user would be angry to lose, what analytics genuinely need, and nothing else. Everything else stays in browser storage until a query proves it belongs in a table.

Deliberately not in Postgres: live timer state (device-local, and sessionStorage when anonymous), the AI insights cache (cheap to recompute), planner drafts (still changing shape), task extras such as notes and subtasks (not yet queried remotely), and every ephemeral UI flag — persisting 'is generating' produced stuck spinners after reload, so it is excluded on purpose.

Local storage is the source of truth while the app is open; Postgres is the mirror that makes the product portable. A singleton engine debounces pushes, pulls on start, and guards against feedback loops while a merge is in flight.

• Tasks sync by diff: changed rows are upserted, deletions are tombstones, and cloud-assigned ids are written back locally so a later update targets the right row.
• Sessions and settings sync as a full replace — append-mostly data where a diff adds complexity without adding safety.
• A five-day soft-delete window on tasks makes an accidental delete recoverable, with a scheduled purge afterwards.
• Open work: the session and settings replace is not atomic, so a failed push is not yet non-destructive. Making it transactional is the next data-layer task.

Sound is the feature most likely to break the timer. It is implemented as a non-React singleton wrapped around Howler: five ambient channels with independent volume, a separate music path, and playback state that lives nowhere in the stores. The stores hold declarative settings; a hook mirrors them into the engine. The engine is imported dynamically on the first user gesture, so it never blocks first paint, and again at completion time, so an alert sound can never be delayed by a missing chunk. Ambient audio and music are mutually exclusive by design, and licensed tracks are served through an authenticated route backed by private storage rather than a public bucket.

The first AI implementation worked and could not be afforded. It consumed credits faster than the product justified, its answers were generic, it recommended paid resources as if everything were free, and it would happily be called with a blocked, dangerous or nonsensical prompt because nothing inspected the request before it reached the model. The rewrite rested on three ideas: bound the spend, bound the input, and make the context structured.

• Models are configuration, not code: one OpenAI-compatible client, with the model and base URL as environment values and presets for several providers plus local inference.
• Insights are evidence-gated: confidence is forced low under ten sessions, chronotype and causation claims are forbidden, and the 21-day habit myth is explicitly banned.
• User-supplied URLs pass an SSRF guard: HTTP(S) only, ports 80 and 443, private and cloud-metadata hosts rejected.
• Every AI route checks origin, authentication, configuration and quota before a model is called.

Most insight in the product costs nothing to produce. Sessions are bucketed locally into peak hours, streaks, weekly minutes, estimate accuracy and break behaviour, then run through a deterministic rule engine with small-sample guards — a rule that fires on three sessions is noise, so it does not. The AI analysis sits above that layer, requires a minimum amount of history, and is cached until the user asks for a fresh one.

• Unit and integration tests over stores, timer logic, sync, AI schemas, normalisation and the security surface.
• End-to-end browser flows across Chromium, Firefox and WebKit, each starting from a clean storage state.
• Security tests for identity isolation, origin checks, SSRF, rate-limit bypass and input size limits.
• Continuous integration runs the linter, a strict type check, a Capacitor configuration guard and the build on every push to main.
• A static quality gate asserts design-system rules, and the performance fixes found in the Lighthouse audit are asserted as tests so they cannot regress silently.

pnpm install
cp .env.example .env.local   # Supabase, AI provider, Redis, Stripe are all optional to start
pnpm dev                     # runs offline-first as a local user without any credentials
pnpm test                    # unit, integration and security suites
pnpm lint && pnpm exec tsc --noEmit

The product runs fully offline as a local user when no Supabase credentials are present — the account layer is an addition, never a precondition.

• Session and settings sync is a full replace, not a diff, so a failed push is not yet non-destructive.
• Planner data and task extras are still device-local until the sync engine covers them.
• The Android wrapper is gated behind device and store checks: release signing, closed testing and the store listing are open work.
• Some pricing copy still advertises 200 weekly AI generations while the enforced premium quota is 120 — the copy, not the limit, is what needs fixing.
• Local Lighthouse performance is still below the production target; the fixes are known and partly asserted as tests.