bytelyst/learning_ai_clock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
449b2dc514
learning_ai_clock/docs/roadmap.md

62 KiB
Raw Blame History

ChronoMind — Product Roadmap

Product: ChronoMind — AI-Powered Time Awareness Layer Product ID: chronomind (ByteLyst ecosystem) Strategy: Option D — Web PWA (MVP) → SwiftUI (iOS/Watch/Mac) → Android (v2) Version: 2.0 (revised per roadmap-v2-review.md audit) Created: February 2026 License: Closed-source app; timer engine library open-source (TBD license) See also: PRD.md | INDUSTRY_RESEARCH.md | roadmap-v2-review.md

Backend: Platform-service in learning_ai_common_plat (Fastify, port 4003) — reuses 17+ existing modules (auth, subscriptions, stripe, invitations, referrals, settings, flags, telemetry, waitlist, ratelimit, usage, plans, licenses, etc.). Only 4 new modules needed: timers, routines, shared-timers, households.

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: Platform-service (Fastify, port 4003) — Cosmos DB sync         │
│  Analytics: Platform-service telemetry / Plausible (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

  • Pre-work (before coding)

    • Register domain: chronomind.app or chronomind.io (needed for deployment + Universal Links)
    • Set up DNS for Vercel deployment
    • Low-fi wireframes: timeline, create timer, Pomodoro, alarm overlay (1 day)
    • Define urgency level color mapping from @bytelyst/design-tokens + ChronoMind product section

  • Project scaffold (6ac54d7)

    • npx create-next-app@latest with Next.js 16, App Router, TypeScript
    • TailwindCSS v4 setup + Lucide React icons
    • Zustand store with localStorage persistence (da4f3b5)
    • ESLint + Vitest config
    • Basic folder structure: app/, components/, lib/
    • GitHub Actions CI: lint + typecheck + vitest on PR (02f9a5f)
    • Auto-deploy to Vercel on main push
    • Analytics stub: lib/analytics.ts — console in dev, no-op in prod, wired into store.ts
    • Track: timer created, timer completed, cascade fired, Pomodoro completed, PWA installed

  • Timer engine (lib/timer-engine.ts) (6ac54d7)

    • 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 for UI countdown display (smooth 60fps in active tab)
    • setInterval in Service Worker for background notification scheduling (30s check)
    • Both contexts needed: rAF stops when tab hidden, SW runs in background
    • Unit tests for timer state transitions (23 tests)

  • Pre-warning cascade (lib/cascade.ts) (6ac54d7)

    • Cascade presets (aligned with PRD): Aggressive, Standard, Light, Minimal, None, Custom
    • 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 (17 tests)

  • Urgency system (lib/urgency.ts) (6ac54d7)

    • 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

  • Dashboard with timer list (components/Dashboard.tsx) (da4f3b5)

    • Timer list showing all active/upcoming timers sorted by fire time
    • Color-coded by urgency level
    • Current time display in header with smooth animation
    • Pre-warning cascade progress bar on each timer card
    • Timer cards with full details (countdown, urgency, state, actions)
    • Empty state: "No active timers — Create your first timer"

  • Create timer flow (components/CreateTimerModal.tsx) (da4f3b5)

    • Quick timer: one-tap presets (5m, 15m, 25m, 45m, 1h) via QuickTimerBar (6b46384)
    • Alarm: time picker, label, urgency selector, cascade preset
    • Countdown: duration picker (hours, minutes, seconds), label, urgency
    • Form validation with Zod
    • Save to Zustand store → localStorage

  • Clock display in header (da4f3b5)

    • Current time with AM/PM in header
    • Date display in header
    • Next timer countdown shown in tab title
    • Responsive: compact in app header

Week 2: Notifications + Polish

  • Notifications (lib/notifications.ts) (da4f3b5)

    • Request notification permission on first timer creation
    • Service Worker registration via Serwist (@serwist/next) (28dfa9f)
    • 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 (a1120a5)

  • Sound system (lib/sounds.ts) (b39652a)

    • Web Audio API setup with AudioContext
    • 5 urgency-mapped alarm tones (programmatic oscillator — no audio files)
    • Volume mapping per urgency level
    • Sound preview in settings page (cad95be)
    • Graceful fallback if audio blocked by browser

  • Tab title countdown (integrated in Dashboard.tsx) (da4f3b5)

    • Show "MM:SS — Label | ChronoMind" in browser tab title
    • Update every tick for active timer
    • Flash title when timer fires (alternating bell/alarm) (d2b5563)
    • Restore original title when no active timers

  • Alarm overlay (components/AlarmOverlay.tsx) (da4f3b5)

    • Full-screen overlay for CRITICAL urgency
    • Pulsing animation
    • Large "Dismiss" button (with confirmation for Critical)
    • "Snooze 5m / 15m" buttons
    • Cannot be accidentally dismissed (Critical requires "Confirm Dismiss")

  • Pomodoro timer (components/PomodoroView.tsx) (6b46384)

    • Work/break cycle configuration (default: 25m work, 5m break, 4 rounds, 15m long break)
    • Visual progress ring showing time remaining (CountdownRing.tsx)
    • Round counter (e.g., "Round 2 of 4") with dot indicators
    • Auto-transition between work and break
    • Session complete celebration (trophy + stats) (35f53e8)

  • Dark + light theme (2a4d66f)

    • System preference detection (prefers-color-scheme) (d2b5563)
    • Manual toggle in header (Sun/Moon icon)
    • Theme persisted to localStorage
    • All components themed via CSS custom properties (--cm-*)

  • PWA setup (ace036b, 28dfa9f)

    • Serwist service worker configuration (28dfa9f)
    • Web app manifest (name, icons, theme color, display: standalone)
    • Offline support: app shell cached via Serwist precache + runtime cache
    • Install prompt UI (components/InstallPrompt.tsx) — beforeinstallprompt listener, dismissable banner
    • PWA metadata in layout (apple-web-app-capable, theme-color)

  • Keyboard shortcuts (6b46384)

    • N — new timer
    • Q — quick timer modal
    • Space — start/pause active timer
    • Esc — dismiss alarm / close modal
    • ? — show shortcuts overlay

  • Landing page (app/landing/page.tsx) (ace036b)

    • Hero: tagline "Never be caught off-guard again"
    • 6 key features with icons (Pre-warnings, Timeline, Urgency, Pomodoro, Smart Defaults, Privacy)
    • "Try it now" button → app dashboard (no signup needed)
    • Social proof section (placeholder for neurodivergent community)
    • Footer: links, GitHub, privacy
    • Privacy policy page (/privacy)
    • Terms of service page (/terms)

  • First-run onboarding (partial) (da4f3b5)

    • 3-step walkthrough: create timer → set cascade → see timeline
    • "Create your first timer" prompt on empty dashboard
    • Tooltip hints on cascade and urgency pickers

  • Feedback mechanism (d2b5563)

    • Feedback button in app (floating FAB, opens GitHub Issues)
    • Bug report button with auto-attached browser info

  • Web accessibility (WCAG 2.1 AA) (partial)

    • Keyboard navigation works for all flows (N, Q, Space, Esc, ?) (6b46384)
    • Screen reader tested (NVDA/VoiceOver) on timeline and timer creation
    • Focus indicators on all interactive elements (:focus-visible ring)
    • Sufficient color contrast for all urgency levels (dark + light themes)
    • aria-label on all icon-only buttons in Dashboard header
    • Skip-to-content link for keyboard/screen reader users

  • Timer accuracy tests (partial) (755d030)

    • Timer fire test: create timer, tick past target, verify fires (store tests)
    • Service Worker notification timing tests
    • Stress test: 50 concurrent timers with cascades → all fire correctly

  • Offline resilience strategy

    • Document SW lifecycle: timers survive SW termination via IndexedDB timestamps + SW periodicsync
    • Background sync queue for analytics events
    • IndexedDB size limit handling (warn user, purge old history)
    • "Tab must be open for notifications" disclaimer for iOS Safari

Phase 1 Exit Criteria

  • PWA installs and works offline on Chrome, Safari, Firefox
  • Timer fires with cascade pre-warnings at correct times (53 passing tests)
  • Notifications work on desktop Chrome, Android Chrome
  • iOS Safari: tab title countdown works (notification best-effort)
  • Pomodoro completes full 4-round session correctly (tested)
  • Lighthouse PWA score > 90
  • Page load < 2 seconds
  • All Vitest unit tests pass (302 tests)
  • Deployed to Vercel with custom domain
  • CI/CD pipeline running (GitHub Actions) (02f9a5f)
  • Analytics tracking timer creation and cascade engagement (lib/analytics.ts wired into store)
  • WCAG 2.1 AA: keyboard nav implemented (6b46384)
  • Privacy policy published at /privacy (ace036b)
  • 5 beta testers using it daily (measured via analytics)

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) (8fe5e8e)

    • Routine data model: ordered array of steps (label, duration, transition type)
    • Transition types: immediate, 1m break, 5m break, custom
    • Routine state machine: ready → active → paused → completed/cancelled
    • Auto-advance between steps with transition notification
    • Pause/resume entire routine (pauses current step timer)
    • Skip step button
    • 4 built-in templates (Morning, Workout, Cooking, Wind-Down)
    • Template instantiation for reuse
    • Unit tests for multi-step routines with transitions (45 tests)

  • Routine editor (components/RoutineEditor.tsx)

    • Add/remove/reorder steps (arrow buttons)
    • Per-step: label, duration, transition type, notes
    • Built-in templates: Morning (5), Workout (4), Cooking (4), Wind-Down (4)
    • Save routine as reusable template (checkbox toggle)
    • Total duration display (auto-calculated, includes transitions)
    • Preview timeline of routine

  • Routine runner (components/RoutineRunner.tsx)

    • Full-screen routine execution view with countdown ring
    • Current step highlighted with countdown ring + label
    • Next step preview with duration
    • Progress bar showing overall routine progress
    • Step dot indicators (completed/skipped/active/pending)
    • "Done early" button to advance + Skip + Pause/Resume
    • Completion celebration with step summary
    • Routine store (lib/routine-store.ts) with Zustand + localStorage persistence
    • Auto-advance steps via tickRoutines() on rAF loop
    • Routines page (app/routines/) with template browser, runner, history

  • Linked timers (lib/linked-timers.ts)

    • "When timer A ends, start timer B" chain relationships
    • Chain building, append, remove with automatic relinking
    • Linked timer presets: Pasta, Laundry, Meeting Prep
    • Cancel chain helpers (hasDownstreamTimers, getDownstreamTimerIds)
    • Chain queries: getNextInChain, findChainForTimer, getChainPosition
    • Chain visualization in timeline
    • Unit tests (27 tests)

  • Natural language input (lib/nl-parser.ts + CreateTimerModal integration) (8fe5e8e, 065bb1b)

    • Regex-based parser (no chrono-node dependency needed)
    • Examples: "Standup in 30 minutes", "Wake up at 6:30am", "Remind me at 3pm to call Mom", "pomodoro 4 rounds"
    • Extract: time, duration, label, urgency hints ("important meeting" → Important)
    • Integrated into CreateTimerModal with live parse preview
    • Parse preview: show parsed timer type, label, duration, urgency before confirming
    • Enter-to-create shortcut for quick creation
    • Unit tests for 37 natural language patterns

Week 4: Focus Mode + Stats

  • Focus mode (app/focus/page.tsx + components/FocusView.tsx) (065bb1b)

    • Activate focus: choose duration (6 presets) or "until next timer"
    • Block all notifications except CRITICAL urgency (shield badge)
    • Full-screen focus view with minimal distraction (countdown ring)
    • Ambient background sound options (rain, white noise, coffee shop) — Web Audio API
    • Integration with Pomodoro (25m focus shortcut)
    • Focus session summary on completion (time focused, distractions blocked)

  • Contextual pre-warning messages (lib/context-messages.ts) (8fe5e8e)

    • Based on timer label, generate helpful prep messages
    • Rules engine: "meeting" → "Review your agenda", "flight" → "Check in online", "dentist" → "Bring your insurance card"
    • Keyword → message mapping (20+ categories, expandable)
    • Custom messages per timer (user override)
    • Warning message formatting with time remaining context
    • Unit tests (23 tests)

  • Statistics + streaks (lib/stats.ts + app/history/page.tsx + components/StatsView.tsx + components/StreakCard.tsx)

    • 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 (bar chart for daily activity, line chart for focus time, pie chart for categories)
    • Category breakdown stats
    • History page with search, category filter, urgency filter
    • Timer export/import (JSON) + calendar .ics import on history page
    • Unit tests (23 tests)

  • Categories / tags (lib/categories.ts)

    • Built-in categories: Work, Personal, Health, Cooking, Exercise, Study
    • Custom tags (add/remove, normalized, deduped)
    • Filter dashboard by category (chip filter bar)
    • Category-specific default urgency and cascade presets (auto-applied on selection)
    • Color-coded category indicators on dashboard
    • Category picker integrated into CreateTimerModal
    • Unit tests (29 tests)

  • Recurring timers (lib/recurrence.ts)

    • Recurrence rules: daily, weekday, weekend, weekly, biweekly, monthly, custom (select days)
    • Next occurrence calculation (with configurable lookahead)
    • "Skip next" and "Pause recurring" options
    • Recurring timer badge on timeline
    • Bulk edit: get next N occurrences
    • Unit tests for recurrence edge cases (month boundaries, DST, leap year) (37 tests)
    • Rule builders + human-readable descriptions

Week 5: Calendar + Neurodivergent Mode + Polish

  • Calendar .ics import (lib/calendar-import.ts)

    • Parse .ics file (iCalendar format) with RFC 5545 compliance (line unfolding, text escaping)
    • Import events as alarms with auto-generated cascade (urgency-based preset)
    • Subscribe to calendar URL (re-fetch periodically)
    • Import preview: show events before confirming (preview panel with conflict indicators)
    • Conflict detection: warn if imported event overlaps existing timer (15-min window)
    • Map calendar event priority (1-9) to urgency level
    • Support: UTC datetime, local datetime, date-only events
    • Timer export/import as JSON (lib/export.ts)
    • Unit tests (26 tests)

  • Neurodivergent-friendly design (DEFAULT UX, not a toggle) (partial)

    • Visual countdown ring (components/CountdownRing.tsx) (6b46384)
      • 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) (b39652a)
    • Reduced cognitive load: quick presets, progressive disclosure in create modal
    • Time blindness aids: "About as long as [familiar reference]" (d2b5563)
    • Body doubling placeholder: "Focus with others" room (v3 feature, show coming soon)
    • Toggle in settings: "Compact mode" for power users who want dense UI

  • Prep time intelligence (lib/prep-time.ts)

    • Per-timer: suggested prep + travel time based on label keywords and category
    • Auto-generates prep warnings: "Start preparing now — your meeting is in 20 minutes"
    • Prep time shown on timeline as a colored block before the timer
    • Smart defaults: 12 keyword rules (meeting→10m, flight→2h, cooking→15m, dentist→35m, etc.) + 6 category defaults
    • Prep warning formatter with contextual messages
    • Unit tests (22 tests)

  • Adaptive snooze learning (lib/adaptive-snooze.ts)

    • Track snooze patterns per timer/category (localStorage, max 200 records)
    • After 5+ data points: "You always snooze your morning alarm 3 times. Set it 15 minutes later?"
    • Label normalization for pattern grouping (e.g. "Meeting with Bob" → "meeting with")
    • checkForSnoozeSuggestion() for real-time suggestions on timer creation
    • Suggestion shown as dismissable card on dashboard
    • Accept → auto-adjusts recurring timer
    • Unit tests (22 tests)

  • Event countdown timer (timer-engine.ts createEvent + store addEvent)

    • Days/hours until a future date with milestone warnings (30, 7, 3, 1 days)
    • Timer type event in data model + createEvent factory + store addEvent
    • Event tab in CreateTimerModal with date picker + days-remaining preview
    • Use cases: "132 days until wedding", "47 days until vacation"
    • Visual: large days display with milestone progress bar (color-coded: accent → warning → danger)

  • Timer export / import (local backup) — lib/export.ts + History page

    • "Export timers" → JSON download of all timers
    • "Import timers" → upload JSON to restore (with deduplication)
    • Calendar .ics import on same page
    • CSV export for spreadsheet users
    • Warning banner: "Your timers are stored locally. Export regularly."

  • iOS waitlist

    • Waitlist signup on web landing page ("Get notified when iOS launches")
    • Use platform-service waitlist module (already exists) when backend is connected
    • Fallback: simple email collection form

  • Timer history (app/history/page.tsx)

    • Searchable log of all past timers
    • Filter by category, urgency
    • "Repeat" button to recreate a past timer (alarm at same time, countdown same duration)
    • Export as CSV (Label, Type, State, Urgency, Category, Created, Completed, Duration)

  • Playwright E2E tests (e2e/core-flows.spec.ts, 10 test suites)

    • Create alarm → verify it appears on timeline
    • Create countdown → verify it counts down
    • Create pomodoro → verify round info
    • NL input → verify parsing + timer creation
    • Routines → navigate + verify templates
    • History & Stats → tabs, export CSV, local storage warning
    • Focus mode → navigate + verify presets
    • Event countdown → create with future date + verify days display
    • Settings → compact mode toggle
    • Keyboard shortcuts → ? overlay
    • PWA install flow (requires browser context with installability)

Phase 2 Exit Criteria

  • Routines work end-to-end (create, run, complete, save as template)
  • NL input successfully parses 80%+ of natural time expressions (37 patterns)
  • Focus mode blocks notifications during session
  • Streak tracking persists across sessions
  • Calendar .ics import works with Google Calendar exports
  • Neurodivergent mode is default and noticeably gentler than previous
  • E2E tests written (10 suites in e2e/core-flows.spec.ts), CI integration pending
  • 25+ beta testers, 3+ using routines daily
  • ProductHunt submission prepared (web) — App Store prep moved to Phase 3
  • 373 tests passing across 16 test files

Phase 3: Apple Native — "Own the Wrist" (Week 6-9)

Goal: Ship native iOS + Apple Watch apps. macOS deferred to Phase 4 (4 weeks for iOS + Watch + Live Activities is already aggressive). Success criteria: Apple Watch complications are the #1 reason users love ChronoMind. Framework decision: Fully native SwiftUI (NOT KMP) — see platform analysis in PRD. Note: This phase is 4 weeks, not 3 as PRD states. PRD phases section should be updated to match.

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) — using UserDefaults for v1, SwiftData migration planned
    • Dependency: none beyond Apple frameworks (zero third-party for v1)
    • Minimum deployment: iOS 17, watchOS 10, macOS 14

  • Timer engine Swift port (Shared/TimerEngine/) (partial)

    • Cascade.swift — port from cascade.ts
    • Urgency.swift — port from urgency.ts
    • Recurrence.swift — port from recurrence.ts (Phase 2 web dependency)
    • TimerEngine.swift — port from timer-engine.ts (state machine, factory functions, transitions)
    • NLParser.swift — port from nl-parser.ts (Phase 2 web dependency)
    • ContextMessages.swift — port from context-messages.ts (Phase 2 web dependency)
    • Format.swift — port from format.ts
    • TimeBlindness.swift — port from time-blindness.ts
    • XCTest unit tests: 58 tests passing (TimerEngineTests, CascadeTests, FormatTests)
    • Completed: ~1500 lines of Swift, all core timer logic ported

  • Data models (Shared/) (partial)

    • CMTimer — Codable struct matching web Timer interface (in TimerEngine.swift)
    • CMRoutine + CMRoutineStep (Phase 2 web dependency)
    • CMCategory
    • CMTimerHistory
    • CMUserPreferences
    • Migrate to @Model for SwiftData (currently UserDefaults + JSON)

  • iOS screens (partial)

    • TimelineView — vertical timeline with clock header, next-up card, quick timer bar, active/recent lists
    • CreateTimerView — alarm, countdown, pomodoro creation with urgency/cascade selectors
    • QuickTimerSheet — bottom sheet with 12 one-tap presets + time references
    • RoutineListView + RoutineRunnerView (Phase 2 web dependency)
    • PomodoroView — focus session with countdown ring, round tracking, auto-transitions
    • HistoryView — past timers, stats (completion rate, type breakdown, snooze count)
    • SettingsView — notifications, haptics, sound, default urgency/cascade, data management
    • Tab navigation: Timeline | Focus | History | Settings
    • AlarmOverlay — full-screen critical alarm with confirm-to-dismiss
    • CountdownRing — visual countdown with color transitions (green→yellow→orange→red)
    • TimerCard — timer display with state indicators, cascade progress, actions
    • UrgencyBadge, CascadeProgressBar, FiringCard components

  • 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 (interruptionLevel)
    • Custom notification sounds per urgency (using system defaults for v1)
    • 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) — needs background audio session

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: AI Reschedule + Gamification

Note: macOS menu bar app deferred to Phase 4 (Week 10-11). Phase 3 focuses on iOS + Watch quality.

  • 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: 3-day, 7-day, 14-day, 30-day, 60-day, 100-day, 200-day, 365-day
    • Focus score: weekly score based on on-time rate + focus hours + consistency + low snooze
    • Weekly summary card (shareable image via ImageRenderer — key for viral growth)
    • Gentle celebration animations (confetti for streak milestones, not obnoxious)

Week 9: iPad + Polish + TestFlight

  • iPad layout

    • iPad sidebar navigation (NavigationSplitView)
    • Wider timeline with side panel for timer detail
    • Stage Manager / multiple window support (iPadOS 16+ via NavigationSplitView)

  • Cross-device continuity

    • Handoff: start timer on Mac, see it on iPhone and Watch (deferred to Phase 4)
    • iCloud sync for timer data (NSUbiquitousKeyValueStore + merge strategy)
    • Shared UserDefaults via App Groups (iPhone ↔ Watch ↔ Widget)

  • Accessibility

    • VoiceOver: all screens navigable, timer states announced
    • Dynamic Type: scaled font modifier
    • Reduce Motion: motionSafe() modifier respects system setting
    • High Contrast mode: contrastAdaptive() modifier

  • XCTest + XCUITest

    • Unit tests for timer engine (30 tests, mirroring web Vitest)
    • Unit tests for cascade (18), format (12), urgency (14), accessibility (14)
    • Unit tests for shared timer data (12), reschedule engine (14), gamification (15)
    • 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: MetricKit diagnostics + local storage
    • Feedback form in Settings (bug report, feature request, general)
    • App Store submission prepared (screenshots, description, keywords, preview video)

Phase 3 Exit Criteria

  • iOS app installs and all features work on iPhone 14+ (iOS 17)
  • iPad layout works with sidebar navigation (iPadOS 16+)
  • 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
  • Siri Shortcuts work for top 3 use cases
  • AI reschedule correctly shifts timers
  • 129 XCTests across 8 test files pass
  • TestFlight beta: 100 external testers, crash-free rate > 99%
  • App Store submission prepared and submitted (screenshots, description, keywords, preview video)
  • macOS deferred to Phase 4

Phase 4: Context & Growth — "Make It Sticky" (Week 10-14)

Goal: macOS menu bar, calendar sync, location awareness, cloud sync, and viral growth mechanics. Success criteria: Users say "ChronoMind knows my schedule better than I do."

Week 10-11: macOS + Calendar + Location

  • macOS menu bar app (ChronoMindMac/) — deferred from Phase 3

    • Menu bar icon: shows countdown of next timer
    • Click → popover with mini timeline
    • Quick timer creation from popover
    • Notification center integration (UNUserNotificationCenter)
    • Keyboard shortcut: Cmd+Shift+T → quick timer
    • Share 90%+ code with iOS via Shared/ folder

  • Full calendar sync

    • Google Calendar OAuth 2.0 integration (deferred — needs server-side OAuth)
    • Apple Calendar (EventKit) read access
    • Outlook Calendar (Microsoft Graph API) integration (deferred — needs server-side OAuth)
    • One-way sync: imported events become timers with auto-cascade (read-only)
    • Conflict resolution: calendar events take priority via deterministic IDs
    • Sync frequency: every 15 minutes + on-demand refresh
    • Visual distinction: synced events tagged with isCalendarSync + calendar color
    • Web: OAuth flow in Next.js API routes (deferred)
    • iOS: EventKit for Apple Calendar

  • 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, preset icons)
    • Privacy-first: all location processing on-device, no server tracking
    • Web: use Geolocation API (deferred)

  • Travel time intelligence

    • Apple Maps API (MapKit) for travel time estimates
    • Travel advisory messages: "Leave now — 28 min drive"
    • 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 (deferred)

Week 12: Sleep + Wellness

  • Sleep integration

    • Bedtime routine: customizable wind-down sequence (4-step default)
    • Smart alarm: set a wake window (e.g., 6:30-7:00) with HealthKit optimization
    • 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" via UNCalendarNotificationTrigger
    • Blue light reminder (deferred — no API to trigger Night Shift programmatically)

  • 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" (peak hours + best day)
    • Optional: prompt at consistent times (morning, post-lunch, evening) with rate limiting
    • All data local — never sent to any server

  • Cloud sync (Apple-only via iCloud, privacy-first)

    • iCloud/CloudKit sync for Apple devices only (iPhone ↔ Mac ↔ Watch)
    • Sync scope: timers, routines, categories, preferences, stats
    • Conflict resolution: last-write-wins with vector clocks
    • Opt-in: works perfectly offline, sync is a bonus
    • Cross-platform sync (web ↔ Android) deferred to Phase 5 via platform-service REST API
    • TLS in transit + encrypted at rest in Cosmos DB (E2E encryption deferred — timer data is not sensitive enough to justify complexity)
    • Delete account: wipes all cloud data immediately

  • Data export / account deletion (App Store + GDPR requirement)

    • "Export all my data" → JSON download of all timers, routines, stats, mood check-ins
    • "Delete my account" → wipe UserDefaults, App Group, iCloud KV, notifications, temp files
    • Required before App Store submission (Apple requirement since 2022)

  • Advanced NL parsing (upgrade path from chrono-node)

    • Define timer-parse extraction task in extraction-service (port 4005)
    • Classes: time, duration, urgency_hint, label, recurrence
    • Use @bytelyst/extraction client for LLM-powered parsing
    • Falls back to chrono-node if extraction-service unavailable
    • Enables: "Set a critical alarm for my dentist next Tuesday at 2pm with 1 hour warning and 30 min travel time"

Week 13-14: Viral Growth Mechanics

  • Shareable weekly summary (built in Phase 3 Week 8 gamification)

    • Auto-generated card via WeeklySummaryCard + ImageRenderer
    • Beautiful design (dark bg, accent colors, ChronoMind branding)
    • Share via native ShareLink to any platform
    • Deep link back to ChronoMind in share text
    • #1 viral mechanic — shareable from History → Badges tab

  • Shareable timer

    • Create a timer and share link: "chronomind.app/t/abc123"
    • Recipient opens link → timer auto-added via importFromURL
    • Use case: "Here's the pasta recipe timing" / "Here's our meeting prep timer"
    • Web link works without app (PWA fallback URL)
    • iOS: Universal Link → canHandleURL + extractShareCode

  • Referral program

    • "Invite a friend → both get 1 month Pro free"
    • Unique referral code per user (CM-XXXX format)
    • Track referral chain (incoming/outgoing history)
    • Show referral count + Pro reward months

  • 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

  • macOS menu bar app works on macOS 14+ (ChronoMindMac/)
  • Calendar sync works with Apple Calendar via EventKit (Google/Outlook deferred)
  • Location triggers fire reliably (CoreLocation geofencing)
  • Travel time estimates adjust pre-warning cascade (MapKit)
  • Sleep data integration working via HealthKit
  • Data export and account deletion functional (GDPR compliant)
  • Weekly summary card shareable to any platform via ShareLink
  • Shareable timer links work (universal links + import)
  • Referral program with unique codes and Pro rewards
  • ProductHunt page live, launch scheduled (non-code)
  • App Store listing approved and live (non-code)
  • 500+ users (web + iOS combined) (growth metric)
  • 4.5+ star rating on App Store (growth metric)

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) — deferred, using in-memory for MVP
    • Hilt for dependency injection
    • Minimum SDK: API 26 (Android 8.0)
    • Gradle version catalog for dependency management (libs.versions.toml)

  • Timer engine Kotlin port (TimerEngine/)

    • Port from Swift: Models.kt + TimerEngine.kt (create, pause, resume, fire, snooze, dismiss, complete, cascade, format)
    • UrgencyLevel, CascadePreset, PomodoroConfig, PomodoroState all ported
    • 30 JUnit5 tests mirroring XCTest and Vitest tests
    • Completed in single session

  • Android screens (Jetpack Compose)

    • TimelineScreen — vertical timeline with timer cards + FAB create dialog
    • CreateTimerScreen — inline dialog with label, slider, presets
    • RoutineScreen — deferred to next sprint
    • FocusScreen — Pomodoro session with round tracking
    • HistoryScreen — stats chips + completed/dismissed list
    • SettingsScreen — urgency, cascade, sound, haptic, data export/delete, about
    • Bottom navigation matching iOS tab structure (4 tabs)

  • Android notifications

    • AlarmManager for exact alarm scheduling (pre-warnings)
    • 6 notification channels (critical, important, standard, gentle, passive, warning)
    • Full-screen intent for CRITICAL urgency
    • Notification actions: Snooze 5m, Dismiss (via TimerAlarmReceiver)
    • Foreground service for active countdown display (deferred)
    • SCHEDULE_EXACT_ALARM + USE_EXACT_ALARM permission handling (Android 12+)

  • Android widgets

    • Glance widgets (Jetpack Glance) with XML provider configs
    • Small: next timer countdown (2x2)
    • Medium: next 3 timers (4x2)
    • Large: mini timeline (4x3)
    • Widget tap → actionStartActivity<MainActivity>

  • 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 with Material theme
    • WearTimelineScreen — ScalingLazyColumn scrollable timeline
    • WearTimerChip — urgency-colored timer chips
    • Tile: next timer complication (deferred)
    • Haptic pre-warnings (deferred — needs phone↔watch data layer)
    • Dismiss/snooze from wrist (deferred — needs phone↔watch data layer)

  • Cross-platform cloud sync (via platform-service)

    • Sync API: platform-service REST endpoints for timer CRUD + sync (productId: "chronomind")
    • JWT authentication via @bytelyst/auth (reuse existing module)
    • TLS in transit + encrypted at rest in Cosmos DB
    • Sync protocol: last-write-wins with conflict detection
    • Works across: Web ↔ iOS ↔ macOS ↔ Android (replaces Phase 4 iCloud-only sync)
    • Account creation: Apple Sign-In / Google Sign-In (email/password requires platform-service Email Delivery + Password Reset — may not be ready)
    • Register chronomind as product in platform-service products module

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 (deferred to v3)

    • Experimental feature requiring real-time infrastructure (Event Bus). Defer until platform gap component 2.4 is built.
    • v3 scope: "Focus room" — virtual co-working, see others' timers (anonymized), shared ambiance

  • 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 (Phase 1-2) v1 Target (Phase 3-4) v2 Target (Phase 5)
PWA installs 100 500 2,000
DAU 50 200 1,000
MAU 150 1,000 5,000
DAU/MAU ratio > 33% > 50% > 50%
Timers created/week 500+ 5,000+ 25,000+
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%
Snooze rate < 40% < 30% < 25%

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; neurodivergent-friendly default
10 Monetization too early kills growth Low 4 Free for 3 phases; only monetize when PMF is proven
11 Platform-service Email Delivery not ready for Phase 4 accounts Medium 4 Fallback: Apple Sign-In / Google Sign-In only (skip email/password)
12 Platform-service Event Bus not ready for Phase 5 shared timers Medium 5 Fallback: polling (30s interval) instead of real-time push
13 Service Worker termination loses timer state Medium 1 Persist all state to IndexedDB; SW checks timestamps on wake, not in-memory
14 Design token conflict with ByteLyst ecosystem Low 1 ChronoMind gets own product section in token file; shared base, own semantics

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) App Groups shared WKExtension notifications
macOS SwiftUI (macOS 14+) AppKit (menu bar) SwiftData (shared via iCloud) UNUserNotificationCenter
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 Platform-service (Fastify 5, port 4003) in learning_ai_common_plat @bytelyst/auth (JWT), @bytelyst/cosmos, @bytelyst/config Azure Cosmos DB (productId: "chronomind") Platform-service notifications module

Appendix B: Cost Estimation

Item Phase Monthly Cost Notes
Vercel (web hosting) 1+ $0 (free tier) Hobby plan covers MVP easily
Domain 1+ ~$12/yr .app or .io domain
Azure Cosmos DB 4+ ~$25-50/mo Serverless tier, productId: "chronomind" partition
Apple Developer Program 3+ $99/yr Required for App Store + TestFlight
Google Play Console 5+ $25 one-time Required for Play Store
Plausible Analytics 1+ $0 (self-hosted) or $9/mo Or use platform-service telemetry (free)
Stripe 5+ 2.9% + 30¢ per transaction Pro/Family subscription processing
Total (Phase 1-3) ~$10/mo Minimal — mostly free tiers
Total (Phase 4-5) ~$75-100/mo Cosmos DB + domain + Apple program

Note: Platform-service infrastructure (Cosmos DB, AKV, health checks) is shared with LysnrAI. ChronoMind's incremental cost is only additional Cosmos RUs for timer data.

Appendix C: Common Platform Reusability

ChronoMind reuses 13 shared packages and 17+ platform-service modules from learning_ai_common_plat:

Package ChronoMind Use Phase
@bytelyst/auth JWT auth for Pro/Family accounts 4-5
@bytelyst/react-auth Web dashboard auth context 4-5
@bytelyst/api-client Web → sync API calls 4-5
@bytelyst/config Config + productId: "chronomind" + AKV 4-5
@bytelyst/cosmos Cosmos DB for cloud sync, shared timers 4-5
@bytelyst/errors Typed HTTP errors 4-5
@bytelyst/logger Server-side structured logging 4-5
@bytelyst/design-tokens Cross-platform design system 1+
@bytelyst/monitoring Health-check utilities 5
@bytelyst/blob Custom alarm sound uploads 5
@bytelyst/extraction Advanced NL parsing via extraction-service 4+
@bytelyst/testing Shared test mocks 4-5
@bytelyst/fastify-core Service app factory 5

New platform-service modules needed (4):

  • timers — timer CRUD + sync for productId: "chronomind"
  • routines — routine CRUD + sync
  • shared-timers — household shared timer management
  • households — household membership + invitations

Appendix D: Key Decisions

# Decision Options Recommendation Rationale
1 Backend stack Platform-service vs Cloudflare Workers Platform-service Reuses 17+ existing modules
2 Apple-only sync CloudKit vs skip until Phase 5 CloudKit for Phase 3-4 Free, fast for Apple-only
3 E2E encryption Full E2E vs TLS + at-rest TLS + at-rest Timer data not sensitive enough
4 Real-time shared timers WebSocket vs SSE vs polling SSE + polling fallback WebSocket overkill for timers
5 Design tokens Extend bytelyst.tokens.json ChronoMind product section Shared base, own urgency colors
6 Analytics Plausible vs PostHog vs telemetry Platform-service telemetry Free, self-hosted, integrated
7 Phase 3 scope iOS + Watch + Mac vs iOS + Watch iOS + Watch; Mac in Phase 4 4 weeks already aggressive
8 Calendar sync Two-way vs one-way One-way (read-only) Two-way is fragile
9 Body doubling Phase 5 vs v3 Defer to v3 Needs Event Bus infrastructure
10 Domain name chronomind.app vs .io Check availability pre-Phase 1 Needed for deployment
11 Open-source Full vs closed vs hybrid Hybrid: open timer engine lib Credibility + community
12 Windows/Tauri Phase 5 vs Phase 6 vs v3 Defer to v3 Focus on mobile first
13 AKV secrets Own CHRONO_SECRETS vs share Share Cosmos/JWT, own Stripe productId partitions data
14 Fonts ByteLyst (DM Sans) vs own (Inter) Own: Inter + JetBrains Mono Superior digit rendering

Windows/Tauri note: PRD lists Windows as v2.0 target. Deferred to v3 — insufficient market signal to justify Tauri investment before mobile platforms are stable. Revisit after Phase 5 Android launch.