From c02d8cf08c4be1489f3671e767d2d7f1596a8935 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Fri, 27 Feb 2026 17:27:05 -0800 Subject: [PATCH] docs: add comprehensive product roadmap (5 phases, Option D strategy) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 1: Web MVP (Next.js 16 PWA) — timer engine, cascade, visual timeline - Phase 2: Intelligence — routines, NL input, focus mode, neurodivergent mode - Phase 3: Apple Native — iOS + Apple Watch + macOS (SwiftUI, not KMP) - Phase 4: Context & Growth — calendar sync, location, sleep, viral mechanics - Phase 5: Android + Scale — Jetpack Compose, Wear OS, shared timers, monetization - Includes: viral playbook, success metrics, risk register, tech stack summary - Checklists for every phase with exit criteria --- docs/roadmap.md | 884 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 884 insertions(+) create mode 100644 docs/roadmap.md diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..67bf70c --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,884 @@ +# ChronoMind — Product Roadmap + +> **Product:** ChronoMind — AI-Powered Time Awareness Layer +> **Strategy:** Option D — Web PWA (MVP) → SwiftUI (iOS/Watch/Mac) → Android (v2) +> **Created:** February 2026 +> **See also:** [PRD.md](PRD.md) | [INDUSTRY_RESEARCH.md](INDUSTRY_RESEARCH.md) + +--- + +## Executive Summary + +ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-platform product: + +| Phase | Timeline | Platform | Goal | +|-------|----------|----------|------| +| **Phase 1** | Week 1-2 | Web PWA | Ship MVP — validate core concept | +| **Phase 2** | Week 3-5 | Web PWA | Intelligence layer — make it smart | +| **Phase 3** | Week 6-9 | iOS + Apple Watch + macOS | Go native — own the wrist | +| **Phase 4** | Week 10-14 | All Apple + Web | Context, sync, growth — make it sticky | +| **Phase 5** | Week 15-22 | + Android + Wear OS | Full platform — scale to everyone | + +**North star metric:** Daily Active Users who set a timer with pre-warnings enabled. + +--- + +## Architecture Overview + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ ChronoMind Architecture │ +├──────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Track 1: Web (Next.js 16) Track 2: Apple (SwiftUI) │ +│ ───────────────────────── ──────────────────────── │ +│ src/lib/timer-engine.ts ──port──→ Shared/TimerEngine/*.swift │ +│ src/lib/cascade.ts ──port──→ Shared/TimerEngine/Cascade.swift│ +│ src/lib/recurrence.ts ──port──→ Shared/TimerEngine/Recurrence. │ +│ src/lib/store.ts (Zustand+IDB) Shared/Store/ (SwiftData) │ +│ src/components/ (React) ChronoMind/ (iOS SwiftUI) │ +│ ChronoMindWatch/ (watchOS) │ +│ ChronoMindMac/ (macOS menu bar) │ +│ │ +│ Track 3: Android (v2) │ +│ ────────────────────── │ +│ TimerEngine/*.kt (Kotlin port) │ +│ UI: Jetpack Compose │ +│ Watch: Wear OS + Glance widgets │ +│ │ +│ Shared: Cloud Sync API (optional, E2E encrypted) │ +│ Analytics: Plausible / PostHog (privacy-first) │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Web MVP — "Make It Work" (Week 1-2) + +> **Goal:** Ship a functional PWA that validates the core concept — pre-warning cascades make timers actually useful. +> **Success criteria:** 10 people use it daily for a week and say "I can't go back to a normal timer." + +### Week 1: Foundation + Timer Engine + +- [ ] **Project scaffold** + - [ ] `npx create-next-app@latest` with Next.js 16, App Router, TypeScript + - [ ] TailwindCSS v4 setup + shadcn/ui init + Lucide React icons + - [ ] Zustand store with IndexedDB persistence (via `idb`) + - [ ] ESLint + Prettier + Vitest config + - [ ] Basic folder structure: `app/`, `components/`, `lib/`, `styles/` + +- [ ] **Timer engine (`lib/timer-engine.ts`)** + - [ ] `Timer` interface with all fields (id, type, label, urgency, targetTime, duration, cascade, etc.) + - [ ] Create timer (alarm, countdown, pomodoro) + - [ ] Start / pause / resume / cancel countdown + - [ ] Timer state machine: `idle → active → warning → firing → snoozed → dismissed` + - [ ] `requestAnimationFrame` + `setInterval` dual-loop for accurate countdown + - [ ] Unit tests for timer state transitions + +- [ ] **Pre-warning cascade (`lib/cascade.ts`)** + - [ ] Cascade presets: Relaxed (2h, 1h, 30m), Standard (1h, 30m, 15m, 5m), Tight (30m, 15m, 5m, 1m), Critical (2h, 1h, 30m, 15m, 5m, 1m) + - [ ] Custom cascade builder (user picks intervals) + - [ ] Cascade scheduler: calculate all warning timestamps from target time + - [ ] Cascade state tracking: which warnings have fired + - [ ] Unit tests for cascade calculation edge cases (past warnings, overlapping, etc.) + +- [ ] **Urgency system (`lib/urgency.ts`)** + - [ ] 5 levels: Critical, Important, Standard, Gentle, Passive + - [ ] Each level maps to: notification style, sound, vibration, visual intensity, snooze behavior + - [ ] Critical: persistent sound, full-screen overlay, no auto-dismiss + - [ ] Passive: badge only, no sound + +- [ ] **Visual timeline dashboard (`components/Timeline.tsx`)** + - [ ] Vertical timeline showing all timers for today/upcoming + - [ ] Color-coded by urgency level + - [ ] Current time marker with smooth animation + - [ ] Pre-warning markers on timeline (small dots before each timer) + - [ ] Tap timer → expand to show details + - [ ] Empty state: "Your day is clear — set your first timer" + +- [ ] **Create timer flow (`app/(app)/create/`)** + - [ ] Quick timer: one-tap presets (5m, 15m, 25m Pomodoro, 1h) + - [ ] Alarm: date + time picker, label, urgency dropdown, cascade preset + - [ ] Countdown: duration picker (hours, minutes, seconds), label, urgency + - [ ] Form validation with Zod + - [ ] Save to Zustand store → IndexedDB + +- [ ] **Large digital clock (`components/Clock.tsx`)** + - [ ] Current time with seconds, subtle glow effect + - [ ] Date display below + - [ ] Next timer countdown shown prominently + - [ ] Responsive: hero on landing, compact in app header + +### Week 2: Notifications + Polish + +- [ ] **Notifications (`lib/notifications.ts`)** + - [ ] Request notification permission on first timer creation + - [ ] Service Worker registration via Serwist (`@serwist/next`) + - [ ] Schedule pre-warning notifications at cascade timestamps + - [ ] Different notification styles per urgency (title, body, icon, sound tag) + - [ ] Notification click → open app to timer detail + - [ ] Fallback: in-app toast if notifications denied + +- [ ] **Sound system (`lib/sounds.ts`)** + - [ ] Web Audio API setup with AudioContext + - [ ] 5 built-in alarm sounds (gentle chime, standard beep, urgent siren, critical alarm, soft bell) + - [ ] Volume mapping per urgency level + - [ ] Sound preview in settings + - [ ] Graceful fallback if audio blocked by browser + +- [ ] **Tab title countdown (`lib/tab-title.ts`)** + - [ ] Show "⏱ 14:32 — Standup" in browser tab title + - [ ] Update every second for active timer + - [ ] Flash title when timer fires (alternating "🔔 TIME!" and timer label) + - [ ] Restore original title when no active timers + +- [ ] **Alarm overlay (`components/AlarmOverlay.tsx`)** + - [ ] Full-screen overlay for CRITICAL urgency + - [ ] Pulsing animation, sound playing + - [ ] Large "Dismiss" button (with confirmation for Critical) + - [ ] "Snooze 5m / 10m / 15m / custom" buttons + - [ ] Cannot be accidentally dismissed (swipe-to-dismiss disabled for Critical) + +- [ ] **Pomodoro timer (`components/PomodoroView.tsx`)** + - [ ] Work/break cycle configuration (default: 25m work, 5m break, 4 rounds, 15m long break) + - [ ] Visual progress ring showing time remaining + - [ ] Round counter (e.g., "Round 2 of 4") + - [ ] Auto-transition between work and break + - [ ] Session complete celebration + +- [ ] **Dark + light theme** + - [ ] System preference detection (`prefers-color-scheme`) + - [ ] Manual toggle in header + - [ ] Theme persisted to localStorage + - [ ] All components themed via CSS custom properties + Tailwind dark mode + +- [ ] **PWA setup** + - [ ] Serwist service worker configuration + - [ ] Web app manifest (name, icons, theme color, display: standalone) + - [ ] Offline support: app shell cached, timers work offline + - [ ] Install prompt UI ("Add to home screen" banner) + - [ ] `manifest.ts` dynamic route for PWA manifest + +- [ ] **Keyboard shortcuts** + - [ ] `N` — new timer + - [ ] `Q` — quick timer modal + - [ ] `Space` — start/pause active timer + - [ ] `Esc` — dismiss alarm / close modal + - [ ] `?` — show shortcuts overlay + +- [ ] **Landing page (`app/page.tsx`)** + - [ ] Hero: animated clock + tagline "Never be caught off-guard again" + - [ ] 3 key features with icons (Pre-warnings, Visual Timeline, Smart Urgency) + - [ ] "Try it now" button → app dashboard (no signup needed) + - [ ] Social proof section (placeholder for future testimonials) + - [ ] Footer: links, GitHub, privacy + +### Phase 1 Exit Criteria + +- [ ] PWA installs and works offline on Chrome, Safari, Firefox +- [ ] Timer fires with cascade pre-warnings at correct times +- [ ] Notifications work on desktop Chrome, Android Chrome +- [ ] iOS Safari: tab title countdown works (notification best-effort) +- [ ] Pomodoro completes full 4-round session correctly +- [ ] Lighthouse PWA score > 90 +- [ ] Page load < 2 seconds +- [ ] All Vitest unit tests pass +- [ ] Deployed to Vercel/Netlify with custom domain +- [ ] 5 beta testers using it daily + +--- + +## Phase 2: Intelligence — "Make It Smart" (Week 3-5) + +> **Goal:** Add the features that make ChronoMind irreplaceable — routines, NL input, focus mode, gamification. +> **Success criteria:** Users create routines and say "This replaced 3 apps for me." + +### Week 3: Routines + Linked Timers + +- [ ] **Routine engine (`lib/routines.ts`)** + - [ ] Routine data model: ordered array of steps (label, duration, transition type) + - [ ] Transition types: immediate, 1m break, 5m break, custom + - [ ] Routine state machine: `ready → step_1_active → step_1_transition → step_2_active → ... → complete` + - [ ] Auto-advance between steps with transition notification + - [ ] Pause/resume entire routine (pauses current step timer) + - [ ] Skip step button + - [ ] Unit tests for multi-step routines with transitions + +- [ ] **Routine editor (`components/RoutineEditor.tsx`)** + - [ ] Add/remove/reorder steps (drag-and-drop) + - [ ] Per-step: label, duration, urgency, notes + - [ ] Routine templates: Morning (5 steps), Evening Wind-down (4 steps), Cooking Prep (3 steps) + - [ ] Save routine as template for reuse + - [ ] Total duration display (auto-calculated) + - [ ] Preview timeline of routine + +- [ ] **Routine runner (`components/RoutineRunner.tsx`)** + - [ ] Full-screen routine execution view + - [ ] Current step highlighted with countdown ring + - [ ] Next step preview + - [ ] Progress bar showing overall routine progress + - [ ] Step transition animation (gentle slide) + - [ ] "Done early" button to advance + +- [ ] **Linked timers (`lib/linked-timers.ts`)** + - [ ] "When timer A ends, start timer B" relationship + - [ ] Chain visualization in timeline + - [ ] Linked timer presets: Pasta (boil water → add pasta → start sauce) + - [ ] Cancel chain option (cancel one, option to cancel all linked) + - [ ] Unit tests for chain execution + +- [ ] **Natural language input (`components/NLInput.tsx` + `lib/nl-parser.ts`)** + - [ ] Integration with `chrono-node` for date/time parsing + - [ ] Examples: "Standup in 30 minutes", "Wake up at 6:30am tomorrow", "Remind me at 3pm to call Mom" + - [ ] Extract: time, duration, label, urgency hints ("important meeting" → Important) + - [ ] Sticky input bar at top of dashboard + - [ ] Parse preview: show parsed timer before confirming + - [ ] Fallback: if parse fails, open manual create form with whatever was understood + - [ ] Unit tests for 20+ natural language patterns + +### Week 4: Focus Mode + Stats + +- [ ] **Focus mode (`app/(app)/focus/`)** + - [ ] Activate focus: choose duration or "until next timer" + - [ ] Block all notifications except CRITICAL urgency + - [ ] Full-screen focus view with minimal distraction + - [ ] Ambient background sound options (rain, white noise, coffee shop) — Web Audio API + - [ ] Integration with Pomodoro (focus mode auto-activates during work intervals) + - [ ] Focus session summary on completion (time focused, distractions blocked) + +- [ ] **Contextual pre-warning messages (`lib/context-messages.ts`)** + - [ ] Based on timer label, generate helpful prep messages + - [ ] Rules engine: "meeting" → "Review your agenda", "flight" → "Check in online", "dentist" → "Leave in X minutes" + - [ ] Keyword → message mapping (expandable, no LLM needed) + - [ ] Custom messages per timer (user override) + - [ ] Show in notification body and on timeline + +- [ ] **Statistics + streaks (`app/(app)/history/`)** + - [ ] Timers created / completed / snoozed / dismissed — daily, weekly, monthly + - [ ] On-time rate: % of timers acted on within 2 minutes of firing + - [ ] Focus time: total hours in focus/Pomodoro mode + - [ ] Current streak: consecutive days with at least 1 completed timer + - [ ] Streak freeze: miss a day but keep streak (1 free freeze per week) + - [ ] Weekly summary card (shareable — great for social/viral) + - [ ] Charts: Recharts (line chart for trends, bar for daily breakdown) + +- [ ] **Categories / tags** + - [ ] Built-in categories: Work, Personal, Health, Cooking, Exercise, Study + - [ ] Custom tags + - [ ] Filter timeline by category + - [ ] Category-specific default urgency and cascade presets + - [ ] Color-coded category indicators on timeline + +- [ ] **Recurring timers (`lib/recurrence.ts`)** + - [ ] Recurrence rules: daily, weekday, weekend, weekly, biweekly, monthly, custom (select days) + - [ ] Next occurrence calculation + - [ ] "Skip next" and "Pause recurring" options + - [ ] Recurring timer badge on timeline + - [ ] Bulk edit: change all future occurrences + - [ ] Unit tests for recurrence edge cases (month boundaries, DST, etc.) + +### Week 5: Calendar + Neurodivergent Mode + Polish + +- [ ] **Calendar .ics import (`lib/calendar-import.ts`)** + - [ ] Parse `.ics` file (iCalendar format) + - [ ] Import events as alarms with auto-generated cascade + - [ ] Subscribe to calendar URL (re-fetch periodically) + - [ ] Import preview: show events before confirming + - [ ] Conflict detection: warn if imported event overlaps existing timer + - [ ] Map calendar event priority to urgency level + +- [ ] **Neurodivergent mode** + - [ ] Visual countdown ring (`components/CountdownRing.tsx`) + - [ ] Large, animated circular countdown (inspired by Time Timer) + - [ ] Color transitions: green → yellow → orange → red as time decreases + - [ ] Optional: fill vs drain animation style + - [ ] Gentle transition alerts (soft chime + visual pulse, not jarring alarm) + - [ ] Reduced cognitive load: hide advanced options by default, progressive disclosure + - [ ] Time blindness aids: "This is about as long as [familiar reference]" (e.g., "25 min — one TV episode") + - [ ] Body doubling placeholder: "Focus with others" room (v2 feature, show coming soon) + - [ ] Toggle in settings: "Gentle mode" (affects sounds, animations, notification style) + +- [ ] **Prep time intelligence** + - [ ] Per-timer: "I need X minutes to prepare" + - [ ] Auto-generates a prep warning: "Start preparing now — your meeting is in 20 minutes" + - [ ] Prep time shown on timeline as a colored block before the timer + - [ ] Smart defaults based on category (meeting → 10m, flight → 2h, cooking → 15m) + +- [ ] **Adaptive snooze learning (`lib/adaptive-snooze.ts`)** + - [ ] Track snooze patterns per timer/category + - [ ] After 5+ data points: "You always snooze your morning alarm 3 times. Set it 15 minutes later?" + - [ ] Suggestion shown as dismissable card on dashboard + - [ ] Accept → auto-adjusts recurring timer + +- [ ] **Timer history (`app/(app)/history/`)** + - [ ] Searchable log of all past timers + - [ ] Filter by category, urgency, date range + - [ ] "Repeat" button to recreate a past timer + - [ ] Export as CSV + +- [ ] **Playwright E2E tests** + - [ ] Create alarm → verify it appears on timeline + - [ ] Create countdown → verify it counts down → fires notification + - [ ] Create routine → run through all steps + - [ ] Pomodoro → complete 4 rounds + - [ ] NL input → verify parsing + - [ ] PWA install flow + +### Phase 2 Exit Criteria + +- [ ] Routines work end-to-end (create, run, complete, save as template) +- [ ] NL input successfully parses 80%+ of natural time expressions +- [ ] Focus mode blocks notifications during session +- [ ] Streak tracking persists across sessions +- [ ] Calendar .ics import works with Google Calendar exports +- [ ] Neurodivergent mode noticeably gentler than default +- [ ] All E2E tests pass in CI +- [ ] 25+ beta testers, 3+ using routines daily +- [ ] App Store / ProductHunt submission prepared + +--- + +## Phase 3: Apple Native — "Own the Wrist" (Week 6-9) + +> **Goal:** Ship native iOS + Apple Watch + macOS apps that make ChronoMind the best timer experience on Apple devices. +> **Success criteria:** Apple Watch complications are the #1 reason users love ChronoMind. +> **Framework decision:** Fully native SwiftUI (NOT KMP) — see [platform analysis in PRD](PRD.md). + +### Week 6: iOS App Foundation + +- [ ] **Xcode project setup** + - [ ] Multi-target Xcode project: ChronoMind (iOS), ChronoMindWatch (watchOS), ChronoMindMac (macOS) + - [ ] Shared Swift package: `Shared/` folder included in all targets + - [ ] SwiftData for persistence (or Core Data if SwiftData has issues) + - [ ] Dependency: none beyond Apple frameworks (zero third-party for v1) + - [ ] Minimum deployment: iOS 17, watchOS 10, macOS 14 + +- [ ] **Timer engine Swift port (`Shared/TimerEngine/`)** + - [ ] `Cascade.swift` — port from `cascade.ts` + - [ ] `Urgency.swift` — port from `urgency.ts` + - [ ] `Recurrence.swift` — port from `recurrence.ts` + - [ ] `Scheduler.swift` — port from `timer-engine.ts` + - [ ] `NLParser.swift` — port from `nl-parser.ts` (use NSDataDetector + custom patterns) + - [ ] `ContextMessages.swift` — port from `context-messages.ts` + - [ ] XCTest unit tests mirroring all Vitest tests from web + - [ ] **Estimated effort: 2-3 days** (~500-800 lines, logic is pure computation) + +- [ ] **Data models (`Shared/Models/`)** + - [ ] `CMTimer` — SwiftData model matching web Timer interface + - [ ] `CMRoutine` + `CMRoutineStep` + - [ ] `CMCategory` + - [ ] `CMTimerHistory` + - [ ] `CMUserPreferences` + - [ ] All models tagged with `@Model` for SwiftData + +- [ ] **iOS screens** + - [ ] `TimelineView` — vertical timeline (main screen, tab 1) + - [ ] `CreateTimerView` — alarm, countdown, pomodoro creation + - [ ] `QuickTimerSheet` — bottom sheet with one-tap presets + - [ ] `RoutineListView` + `RoutineRunnerView` + - [ ] `FocusView` — focus/Pomodoro session + - [ ] `HistoryView` — past timers, stats, streaks + - [ ] `SettingsView` — preferences, categories, sounds, neurodivergent mode + - [ ] Tab navigation: Timeline | Focus | History | Settings + +- [ ] **Notification scheduling (`Shared/Notifications/`)** + - [ ] `UNUserNotificationCenter` for all pre-warnings + - [ ] Schedule cascade notifications when timer is created + - [ ] Critical alerts: request `.criticalAlert` authorization for CRITICAL urgency + - [ ] Time Sensitive notifications for Important urgency + - [ ] Custom notification sounds per urgency + - [ ] Notification actions: Snooze 5m, Snooze 15m, Dismiss + - [ ] Reschedule all notifications when timer is modified + +- [ ] **Haptic engine** + - [ ] `UIImpactFeedbackGenerator` for pre-warning taps + - [ ] Escalating haptic pattern matching urgency (gentle → standard → heavy) + - [ ] Continuous haptic for Critical alarm (repeating pattern until dismissed) + +### Week 7: Apple Watch + Widgets + +- [ ] **Apple Watch app (`ChronoMindWatch/`)** + - [ ] `WatchTimelineView` — compact timeline for wrist + - [ ] `WatchTimerDetailView` — current timer with countdown ring + - [ ] `WatchQuickTimerView` — one-tap presets on Watch + - [ ] Digital Crown: scroll through upcoming timers + - [ ] Haptic pre-warnings on wrist (gentle tap for early warnings, prominent for final) + - [ ] Dismiss/snooze directly from Watch + +- [ ] **Watch complications** + - [ ] `WidgetKit` complications for Watch faces + - [ ] Circular: countdown to next timer + - [ ] Rectangular: next timer label + time remaining + - [ ] Inline: "Standup in 14m" + - [ ] Corner: countdown ring + - [ ] Update complications via `WidgetCenter.shared.reloadAllTimelines()` + +- [ ] **Live Activities + Dynamic Island** + - [ ] `ActivityKit` Live Activity for active countdown/Pomodoro + - [ ] Dynamic Island compact: timer name + countdown + - [ ] Dynamic Island expanded: countdown ring + snooze/dismiss buttons + - [ ] Lock Screen Live Activity: full countdown with cascade progress + - [ ] Auto-start Live Activity when timer enters final 30 minutes + - [ ] End Live Activity when timer is dismissed + +- [ ] **iOS widgets (`WidgetKit`)** + - [ ] Small widget: next timer countdown + - [ ] Medium widget: next 3 timers list + - [ ] Large widget: mini timeline + - [ ] Lock Screen widget: next timer inline + - [ ] Widget tap → deep link to timer in app + - [ ] Timeline provider: update every 5 minutes + on timer change + +- [ ] **Siri Shortcuts** + - [ ] "Set a timer for 25 minutes" → creates countdown + - [ ] "Start my morning routine" → starts saved routine + - [ ] "What's my next timer?" → speaks next timer info + - [ ] App Intents framework for iOS 17+ + - [ ] Shortcuts app integration + +### Week 8: macOS + AI Reschedule + +- [ ] **macOS menu bar app (`ChronoMindMac/`)** + - [ ] Menu bar icon: shows countdown of next timer + - [ ] Click → popover with mini timeline + - [ ] Quick timer creation from popover + - [ ] Notification center integration (native macOS notifications) + - [ ] Keyboard shortcut: `Cmd+Shift+T` → quick timer + - [ ] Share 90%+ code with iOS via Shared/ folder + +- [ ] **AI reschedule** + - [ ] "I slept in 30 minutes" → shift all morning timers by 30m + - [ ] "Skip my next timer" → remove + adjust linked/dependent timers + - [ ] "Push everything back 1 hour" → bulk shift + - [ ] Smart suggestions: detect when user dismisses alarm late → "Shift your morning by X minutes?" + - [ ] Undo reschedule (keep old state for 1 hour) + +- [ ] **Gamification polish** + - [ ] Streak badges: 7-day, 30-day, 100-day + - [ ] Focus score: weekly score based on on-time rate + focus hours + - [ ] Weekly summary card (shareable image — key for viral growth) + - [ ] Gentle celebration animations (confetti for streak milestones, not obnoxious) + +### Week 9: Polish + TestFlight + +- [ ] **Cross-device continuity** + - [ ] Handoff: start timer on Mac, see it on iPhone and Watch + - [ ] iCloud sync for timer data (CloudKit) + - [ ] Shared UserDefaults via App Groups (iPhone ↔ Watch ↔ Widget) + +- [ ] **Accessibility** + - [ ] VoiceOver: all screens navigable, timer states announced + - [ ] Dynamic Type: all text scales + - [ ] Reduce Motion: disable animations when system setting is on + - [ ] High Contrast mode support + +- [ ] **XCTest + XCUITest** + - [ ] Unit tests for timer engine (mirroring web Vitest tests) + - [ ] Unit tests for cascade, recurrence, NL parser + - [ ] UI tests: create timer → verify timeline → fire → dismiss + - [ ] Widget snapshot tests + +- [ ] **TestFlight** + - [ ] Internal build: team testing + - [ ] External beta: 100 testers via TestFlight link + - [ ] Crash reporting: built-in MetricKit + - [ ] Feedback form in Settings + +### Phase 3 Exit Criteria + +- [ ] iOS app installs and all features work on iPhone 14+ (iOS 17) +- [ ] Apple Watch complications update correctly on Watch Series 8+ (watchOS 10) +- [ ] Live Activities show on Dynamic Island and Lock Screen +- [ ] Widgets update on home screen and lock screen +- [ ] macOS menu bar app works on macOS 14+ +- [ ] Siri Shortcuts work for top 3 use cases +- [ ] AI reschedule correctly shifts timers +- [ ] All XCTests and XCUITests pass +- [ ] TestFlight beta: 100 external testers, crash-free rate > 99% +- [ ] App Store submission prepared (screenshots, description, keywords) + +--- + +## Phase 4: Context & Growth — "Make It Sticky" (Week 10-14) + +> **Goal:** Calendar sync, location awareness, sleep integration, and viral growth mechanics. +> **Success criteria:** Users say "ChronoMind knows my schedule better than I do." + +### Week 10-11: Calendar + Location + +- [ ] **Full calendar sync** + - [ ] Google Calendar OAuth 2.0 integration + - [ ] Apple Calendar (EventKit) read access + - [ ] Outlook Calendar (Microsoft Graph API) integration + - [ ] Two-way sync: imported events become timers with auto-cascade + - [ ] Conflict resolution: calendar events take priority, manual timers preserved + - [ ] Sync frequency: every 15 minutes + on-demand refresh + - [ ] Visual distinction: synced events vs manual timers on timeline + - [ ] Web: OAuth flow in Next.js API routes + - [ ] iOS: EventKit for Apple Calendar, OAuth for Google/Outlook + +- [ ] **Location-based triggers** + - [ ] iOS: CoreLocation geofencing (enter/exit region) + - [ ] "Remind me when I leave home" → geofence exit trigger + - [ ] "Remind me when I arrive at office" → geofence enter trigger + - [ ] Saved locations: Home, Work, Gym (user-configured) + - [ ] Privacy-first: all location processing on-device, no server tracking + - [ ] Web: use Geolocation API (less reliable, best-effort) + +- [ ] **Travel time intelligence** + - [ ] Apple Maps API (MapKit) for travel time estimates + - [ ] "Your dentist appointment is in 45 minutes. Leave now — 28 min drive with current traffic." + - [ ] Auto-adjust pre-warning cascade based on real-time travel time + - [ ] Transport mode: driving, transit, walking (user preference per timer) + - [ ] Web: fallback to static estimate (user enters travel time manually) + +### Week 12: Sleep + Wellness + +- [ ] **Sleep integration** + - [ ] Bedtime routine: customizable wind-down sequence + - [ ] Smart alarm: set a wake window (e.g., 6:30-7:00) → alarm fires at optimal time + - [ ] Sleep tracking via HealthKit (Apple) — read sleep data, don't track directly + - [ ] "You slept 6h 20m. Shift your morning by 15 minutes?" (AI reschedule tie-in) + - [ ] Wind-down notifications: "Bedtime in 30 minutes — start winding down" + - [ ] Blue light reminder: "Consider turning on Night Shift" + +- [ ] **Mood/energy check-in** + - [ ] Quick check-in after completing a timer/routine: 😴 😐 😊 🔥 (4 energy levels) + - [ ] Correlate mood with time of day, timer type, sleep data + - [ ] Weekly insight: "You're most productive between 9-11 AM" + - [ ] Optional: prompt at consistent times (morning, post-lunch, evening) + - [ ] All data local — never sent to any server + +- [ ] **Cloud sync (optional, privacy-first)** + - [ ] E2E encrypted sync via CloudKit (Apple) or custom API + - [ ] Sync scope: timers, routines, categories, preferences, stats + - [ ] Conflict resolution: last-write-wins with vector clocks + - [ ] Opt-in: works perfectly offline, sync is a bonus + - [ ] Web: sync via authenticated API (JWT + encrypted payload) + - [ ] Delete account: wipes all cloud data immediately + +### Week 13-14: Viral Growth Mechanics + +- [ ] **Shareable weekly summary** + - [ ] Auto-generated card: "This week: 47 timers completed, 12h focused, 14-day streak 🔥" + - [ ] Beautiful design (dark bg, accent colors, ChronoMind branding) + - [ ] Share to: Instagram Stories, Twitter/X, LinkedIn, iMessage + - [ ] Deep link back to ChronoMind (UTM tracked) + - [ ] **This is the #1 viral mechanic — make it irresistible to share** + +- [ ] **Shareable timer** + - [ ] Create a timer and share link: "chronom.ind/t/abc123" + - [ ] Recipient opens link → timer auto-added to their ChronoMind + - [ ] Use case: "Here's the pasta recipe timing" / "Here's our meeting prep timer" + - [ ] Web link works without app (PWA fallback) + - [ ] iOS: Universal Link → opens app directly + +- [ ] **Referral program** + - [ ] "Invite a friend → both get 1 month Pro free" + - [ ] Unique referral code per user + - [ ] Track referral chain + - [ ] Show referral count in profile + +- [ ] **ProductHunt launch prep** + - [ ] Maker profile + product page + - [ ] Launch video (30s demo: create timer → cascade fires → Watch notification) + - [ ] 5 key screenshots (timeline, Watch, Dynamic Island, routine, focus) + - [ ] First comment prepared (story of why this exists) + - [ ] Schedule for Tuesday 12:01 AM PT (optimal PH launch time) + +- [ ] **App Store Optimization (ASO)** + - [ ] Keywords: "smart timer", "pre-warning alarm", "visual timeline", "focus timer", "routine timer", "ADHD timer", "pomodoro" + - [ ] 10 screenshots: iPhone (6.7" + 6.1"), iPad, Apple Watch, Mac + - [ ] App preview video (15-30s) + - [ ] Subtitle: "Smart Pre-Warning Timer & Routines" + - [ ] Category: Productivity (primary), Lifestyle (secondary) + +- [ ] **Content marketing** + - [ ] Blog post: "Why I Built ChronoMind — The Timer App That Understands Urgency" + - [ ] Twitter/X thread: "I analyzed every timer app. Here's what they all get wrong. 🧵" + - [ ] Reddit posts: r/productivity, r/ADHD, r/apple, r/webdev + - [ ] Hacker News: "Show HN: ChronoMind — AI-powered pre-warning timer (PWA + iOS)" + - [ ] YouTube: 3-minute walkthrough video + +- [ ] **SEO landing page** + - [ ] Target pages: "best timer app 2026", "ADHD timer app", "pre-warning alarm app" + - [ ] Comparison pages: "ChronoMind vs Tiimo", "ChronoMind vs Structured" + - [ ] Blog with timer/productivity tips (SEO content) + +### Phase 4 Exit Criteria + +- [ ] Calendar sync works with Google, Apple, Outlook calendars +- [ ] Location triggers fire reliably (iOS geofencing) +- [ ] Travel time estimates adjust pre-warning cascade +- [ ] Sleep data integration working via HealthKit +- [ ] Weekly summary card shareable to 3+ social platforms +- [ ] Shareable timer links work (web + iOS universal link) +- [ ] ProductHunt page live, launch scheduled +- [ ] App Store listing approved and live +- [ ] 500+ users (web + iOS combined) +- [ ] 4.5+ star rating on App Store (from beta testers) + +--- + +## Phase 5: Android + Scale — "Reach Everyone" (Week 15-22) + +> **Goal:** Ship Android + Wear OS, shared timers, and reach product-market fit. +> **Success criteria:** 5,000 MAU, 4.5+ stars on both App Store and Play Store. + +### Week 15-17: Android App + +- [ ] **Android project setup** + - [ ] Jetpack Compose + Material 3 + Kotlin + - [ ] Room database (mirroring SwiftData schema) + - [ ] Hilt for dependency injection + - [ ] Minimum SDK: API 26 (Android 8.0) + - [ ] Gradle version catalog for dependency management + +- [ ] **Timer engine Kotlin port (`TimerEngine/`)** + - [ ] Port from Swift (which was ported from TypeScript) — all same logic + - [ ] `Cascade.kt`, `Urgency.kt`, `Recurrence.kt`, `Scheduler.kt`, `NLParser.kt` + - [ ] JUnit5 tests mirroring XCTest and Vitest tests + - [ ] **Estimated effort: 2-3 days** (same as Swift port) + +- [ ] **Android screens (Jetpack Compose)** + - [ ] `TimelineScreen` — vertical timeline + - [ ] `CreateTimerScreen` — alarm, countdown, Pomodoro + - [ ] `RoutineScreen` — list + runner + - [ ] `FocusScreen` — focus/Pomodoro session + - [ ] `HistoryScreen` — stats, streaks, history + - [ ] `SettingsScreen` — preferences, categories, neurodivergent mode + - [ ] Bottom navigation matching iOS tab structure + +- [ ] **Android notifications** + - [ ] `AlarmManager` for exact alarm scheduling (pre-warnings) + - [ ] Notification channels per urgency level + - [ ] Full-screen intent for CRITICAL urgency + - [ ] Notification actions: Snooze, Dismiss + - [ ] Foreground service for active countdown display + - [ ] `SCHEDULE_EXACT_ALARM` permission handling (Android 12+) + +- [ ] **Android widgets** + - [ ] Glance widgets (Jetpack Glance) + - [ ] Small: next timer countdown + - [ ] Medium: next 3 timers + - [ ] Large: mini timeline + - [ ] Widget tap → deep link to timer + +- [ ] **Android-specific features** + - [ ] Quick Settings tile: one-tap to create quick timer + - [ ] Persistent notification during active timer + - [ ] DND integration: timer-aware Do Not Disturb + - [ ] Google Calendar integration (CalendarContract) + +### Week 18-19: Wear OS + Polish + +- [ ] **Wear OS app** + - [ ] Compose for Wear OS + - [ ] `WearTimelineScreen` — scrollable timeline + - [ ] `WearTimerScreen` — countdown with rotary input + - [ ] Tile: next timer complication + - [ ] Haptic pre-warnings + - [ ] Dismiss/snooze from wrist + +- [ ] **Cross-platform cloud sync** + - [ ] Sync API: REST endpoints for timer CRUD + sync + - [ ] JWT authentication (reuse from web) + - [ ] E2E encryption: client-side encrypt before upload + - [ ] Sync protocol: last-write-wins with conflict detection + - [ ] Works across: Web ↔ iOS ↔ macOS ↔ Android + - [ ] Account creation: email + password or Apple/Google Sign-In + +### Week 20-21: Shared Timers + Social + +- [ ] **Shared timers (Family/Household)** + - [ ] Create a "household" group (invite via link) + - [ ] Shared timers visible to all household members + - [ ] Real-time sync: one person starts timer, everyone sees it + - [ ] Use cases: "Dinner in 30 minutes", "Leave for school in 15 min" + - [ ] Per-timer: shared vs private toggle + - [ ] Household admin: manage members, remove shared timers + - [ ] Up to 6 members per household (Family tier) + +- [ ] **Body doubling / shared focus (experimental)** + - [ ] "Focus room" — join a virtual co-working session + - [ ] See other participants' focus timers (anonymized) + - [ ] Accountability: "3 people are focusing with you" + - [ ] Optional: audio ambiance shared in room + - [ ] Join public rooms or create private (link invite) + +- [ ] **API + webhooks** + - [ ] REST API: CRUD timers, routines, categories + - [ ] API key authentication + - [ ] Webhook: `timer.fired`, `timer.dismissed`, `routine.completed` + - [ ] Use cases: Zapier integration, smart home triggers + - [ ] Rate limiting: 100 requests/minute per API key + +- [ ] **Smart Home integration** + - [ ] Webhook-based triggers to HomeKit/Alexa/Google Home + - [ ] "When wind-down routine starts → dim lights to 30%" + - [ ] "When morning alarm fires → turn on coffee machine" + - [ ] Shortcuts integration (iOS) for HomeKit scenes + - [ ] IFTTT applet for cross-platform home automation + +### Week 22: Launch + Scale + +- [ ] **Google Play launch** + - [ ] Play Store listing (screenshots, description, video) + - [ ] Play Store Optimization (similar keywords as App Store) + - [ ] Internal testing → Open testing → Production + - [ ] Crash reporting: Firebase Crashlytics + +- [ ] **Monetization activation** + - [ ] Free tier: all core features, local storage, Pomodoro, routines + - [ ] Pro tier ($3.99/mo or $29.99/yr): cloud sync, calendar integration, custom sounds, AI reschedule, advanced stats, location triggers + - [ ] Family tier ($5.99/mo): shared timers (up to 6 members), household coordination + - [ ] Stripe integration (web), StoreKit 2 (iOS), Google Play Billing (Android) + - [ ] Paywall: soft — show feature, explain it's Pro, easy upgrade + - [ ] 7-day free trial for Pro + +- [ ] **Voice control (v2 feature)** + - [ ] In-app voice: "Push everything back 30 minutes" + - [ ] Siri Shortcuts (already done in Phase 3) + - [ ] Google Assistant Actions + - [ ] Alexa Skill (stretch goal) + +- [ ] **Performance + scale** + - [ ] Web: Core Web Vitals all green + - [ ] iOS: 60fps animations, < 50MB app size + - [ ] Android: 60fps, < 40MB APK + - [ ] Watch: complications update within 15 minutes + - [ ] Sync API: < 200ms p99 latency + - [ ] 10,000 MAU target infrastructure + +### Phase 5 Exit Criteria + +- [ ] Android app live on Google Play, 4.5+ stars +- [ ] Wear OS app functional on Pixel Watch / Galaxy Watch +- [ ] Cross-platform sync working (web ↔ iOS ↔ Android) +- [ ] Shared timers working for households (up to 6 members) +- [ ] API + webhooks functional for automation +- [ ] Monetization: Pro + Family tiers active, > 5% conversion rate +- [ ] 5,000+ MAU across all platforms +- [ ] < 0.1% crash rate on all platforms +- [ ] Customer support: < 24h response time + +--- + +## Success & Viral Playbook + +### Metrics That Matter + +| Metric | MVP Target | v1 Target | v2 Target | +|--------|-----------|-----------|-----------| +| **MAU** | 50 | 1,000 | 5,000 | +| **DAU/MAU ratio** | > 40% | > 50% | > 50% | +| **Pre-warning usage** | > 60% of timers | > 70% | > 75% | +| **Routine creation** | > 20% of users | > 30% | > 35% | +| **7-day retention** | > 30% | > 40% | > 50% | +| **30-day retention** | > 15% | > 25% | > 30% | +| **App Store rating** | — | 4.5+ | 4.5+ | +| **Pro conversion** | — | > 3% | > 5% | +| **Streak > 7 days** | — | > 15% of users | > 25% | +| **Shared summary** | — | > 10% weekly | > 20% | + +### Viral Growth Loops + +``` +Loop 1: Weekly Summary Share +User completes week → Beautiful summary card generated → Shares to social → +Friend sees → Clicks link → Downloads ChronoMind → Repeat + +Loop 2: Shared Timer +User creates timer → Shares link with friend/family → Friend opens link → +Timer auto-added → Friend discovers app → Downloads → Repeat + +Loop 3: Household Invite +User activates Family plan → Invites household → Members join → +Members invite THEIR friends → Organic growth + +Loop 4: Content / SEO +User writes about experience → Blog/Reddit/Twitter → Organic search → +New user finds ChronoMind → Downloads → Repeat +``` + +### What Makes ChronoMind Go Viral + +1. **The "aha" moment** — First time a pre-warning fires and user thinks "I would have been late without this." Target: within first 24 hours of use. + +2. **Shareable summaries** — Weekly stats card must be *beautiful* enough that users *want* to share it. Design it like a Spotify Wrapped card. Include streak count, focus hours, on-time rate. + +3. **Apple Watch as walking billboard** — When someone glances at their Watch and sees a ChronoMind complication, their friend asks "What's that?" Word of mouth. + +4. **Routine templates** — "I use ChronoMind's Morning Routine template and it changed my life" → shareable templates that spread. + +5. **Neurodivergent community** — The ADHD community is vocal and supportive online. If ChronoMind genuinely helps with time blindness, they'll evangelize it. Target: r/ADHD, ADHD TikTok, ADHD Twitter. + +6. **ProductHunt launch** — Target top 5 on launch day. Prepare months in advance with a supporter base. + +7. **"Replace 3 apps" narrative** — Position ChronoMind as replacing Clock + Pomodoro + Routine app. Users love consolidation stories. + +### Pricing Strategy for Growth + +``` +Phase 1-2 (Web MVP): 100% free — no friction, maximum adoption +Phase 3 (iOS launch): 100% free — build App Store momentum and reviews +Phase 4 (Growth): Introduce Pro — soft paywall on advanced features +Phase 5 (Scale): Pro + Family — monetize power users and households + +Free forever: Timers, alarms, countdowns, Pomodoro, routines, + visual timeline, pre-warnings, neurodivergent mode, + stats, streaks, categories, keyboard shortcuts + +Pro ($3.99/mo): Calendar sync, location triggers, cloud sync, + custom sounds, AI reschedule, advanced analytics, + travel time, export, priority support + +Family ($5.99/mo): Everything in Pro + shared timers (6 members), + household coordination, family routines +``` + +--- + +## Risk Register + +| # | Risk | Severity | Phase | Mitigation | +|---|------|----------|-------|------------| +| 1 | PWA notifications unreliable on iOS | High | 1 | Tab title countdown + native iOS app in Phase 3 | +| 2 | Feature creep delays MVP | High | 1-2 | Strict scope: alarm + countdown + Pomodoro only for Phase 1 | +| 3 | Apple Watch complications don't update reliably | Medium | 3 | Budget for watchOS debugging; use TimelineProvider with aggressive updates | +| 4 | Calendar OAuth complexity | Medium | 4 | Start with .ics import (Phase 2); full OAuth only in Phase 4 | +| 5 | Competition adds pre-warnings | Medium | All | Ship fast; cascade + urgency + linked timers is hard to replicate | +| 6 | Low App Store visibility | Medium | 3-4 | ASO from day 1; ProductHunt launch; content marketing | +| 7 | Sync conflicts across platforms | Medium | 4-5 | Start with iCloud (Apple-only); cross-platform sync in Phase 5 | +| 8 | Android notification restrictions (Doze, exact alarms) | Medium | 5 | Use `AlarmManager.setExactAndAllowWhileIdle()`; request permissions | +| 9 | User overwhelm — too many features | Medium | 2+ | Progressive disclosure; smart defaults; "simple mode" toggle | +| 10 | Monetization too early kills growth | Low | 4 | Free for 3 phases; only monetize when PMF is proven | + +--- + +## Key Milestones & Dates + +| Milestone | Target Date | Phase | Celebration | +|-----------|-------------|-------|-------------| +| **MVP shipped** (web PWA live) | Week 2 | 1 | First 10 users 🎉 | +| **Intelligence complete** (routines, NL, focus) | Week 5 | 2 | ProductHunt scheduled | +| **iOS + Watch on TestFlight** | Week 9 | 3 | 100 beta testers | +| **App Store launch** | Week 10 | 3→4 | ProductHunt same week | +| **1,000 MAU** | Week 14 | 4 | Blog post celebrating | +| **Android launch** | Week 18 | 5 | Play Store live | +| **5,000 MAU** | Week 22 | 5 | Series of viral pushes | +| **Monetization live** | Week 20 | 5 | Pro + Family tiers | + +--- + +## Appendix: Tech Stack Summary + +| Platform | Framework | Key Libraries | Storage | Notifications | +|----------|-----------|--------------|---------|---------------| +| **Web** | Next.js 16, React 19 | TailwindCSS v4, shadcn/ui, Zustand, Serwist, chrono-node, date-fns, Recharts | IndexedDB (idb) | Web Push + Service Worker | +| **iOS** | SwiftUI (iOS 17+) | SwiftData, WidgetKit, ActivityKit, EventKit, CoreLocation | SwiftData | UNUserNotificationCenter | +| **watchOS** | SwiftUI (watchOS 10+) | WidgetKit (complications), ClockKit | App Groups shared | WKExtension notifications | +| **macOS** | SwiftUI (macOS 14+) | AppKit (menu bar) | SwiftData (shared via iCloud) | NSUserNotificationCenter | +| **Android** | Jetpack Compose | Material 3, Room, Hilt, Glance (widgets), AlarmManager | Room (SQLite) | NotificationManager + AlarmManager | +| **Wear OS** | Compose for Wear OS | Tiles, Complications, Rotary Input | Room (shared) | Wearable notifications | +| **Sync API** | TBD (Fastify or Cloudflare Workers) | JWT auth, E2E encryption | Cosmos DB or D1 | — |