Koku

The problem

Time trackers are usually one of two things: a cloud silo that owns your data, or a dumb stopwatch with no memory of what the time was actually spent on. Notes live somewhere else entirely, a separate app, a separate login, so the record of what you did and the record of what you learned never meet each other.

I wanted one workspace that tracks time, holds notes, and can reason about both, without asking me to trust it with my data by default. Mostly because I didn't trust myself to remember which cloud service I'd signed up for last.

What I built

Koku is a Next.js app that runs entirely against the browser's IndexedDB by default, with an optional cloud mode (sign-in, sync, and a small admin workspace) built on the same codebase:

• Time tracking: a live timer with pause/resume, pomodoro mode, nested child timers, and a break runner that auto-pauses whatever else is running.
• Tasks: a kanban board (open / in progress / paused / done) whose time entries accumulate directly against the task.
• Notes: a TipTap editor with wiki-style [[links]], tags, and a private personal-notes table that's hard-excluded from every admin view and export.
• Knowledge graph: two WebGL graphs (sigma + graphology), one literal, from note links, and one projected, from time entries logged together.
• Reports & AI: monthly analytics with CSV/JSON/PDF/XLSX export, plus bring-your-own-key stand-ups and monthly narrative reports.

Two modes, one codebase

The same build ships as a zero-config local app and as a multi-tenant cloud app, gated by a single LOCAL_MODE flag.

Design decisions

A few calls I'm happy with:

• Outbox sync with load-bearing table order. tasks pushes before timeEntries, so a pushed entry's taskId never points at a task the cloud mirror doesn't have yet. Order matters more than you'd think until you get it wrong once.
• A separate queue for ephemeral state. Live timer/break state goes through its own pendingLiveMutations queue, deliberately excluded from manual sync and tombstoned server-side after 24h.
• Charts split three ways. Pure transforms (lib/charts/segments.ts) feed a centralised theme which feeds presentational components, so the segment maths is fully testable without ever touching a DOM.
• Segmented, not aggregated, day bars. A day renders as a stack of segments, one per work log, instead of one flat bar per day.
• Time entries projected into a graph. Entries have no real links to each other, so they're projected into a graph whose edges mean "these were logged together," weighted by hours.
• Cross-tab leader election for notifications. Web Locks plus a heartbeat lease so three open tabs don't fire three copies of every reminder. The notification's stable tag is the actual guarantee against duplicates; the election just stops the duplicate work from happening in the first place.
• Bring-your-own-key AI. Keys stay in IndexedDB and are forwarded per request, and the audit logger redacts secrets before anything gets logged.

Highlights

• Installable PWA with an offline app shell and live-update detection, open tabs show a refresh icon when a new build ships
• 6 accent themes (terracotta, ocean, forest, lavender, amber, slate), each with a light and dark palette
• Exports to CSV, JSON, PDF, XLSX and iCal
• WebGL knowledge graph (sigma + graphology) with force layout and a side rail
• TipTap editor with wiki-style [[links]], tags and slugs
• Check-in / break / end-of-day notifications with quiet hours and a quick-note composer built into the notification action
• A custom npm run audit chain fails the build on dangerouslySetInnerHTML, eval(, raw .innerHTML =, or a static import of a heavy lib that should stay lazy
• 刻 Icons baked from the glyph at author time, since a browser rasterizing a favicon has no guaranteed CJK font, so the glyph would otherwise collapse into a blank tile

Links

• Source on GitHub