From 1b148757af9c5b0c258b2794624c0758b9ad7f35 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Fri, 27 Feb 2026 20:32:25 -0800 Subject: [PATCH] =?UTF-8?q?docs:=20apply=20V2=20review=20fixes=20to=20road?= =?UTF-8?q?map.md=20=E2=80=94=20comprehensive=20update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P0 Critical: - Sync API: TBD → platform-service (Fastify, port 4003) - Cascade presets: aligned with PRD (Aggressive/Standard/Light/Minimal/None/Custom) - Deprecated APIs: NSUserNotificationCenter → UNUserNotificationCenter, ClockKit removed - Cloud sync: iCloud Phase 3-4, platform-service REST Phase 5 (no contradiction) - productId: chronomind registered in header + sync modules - Open-source: closed-source app, open timer engine lib - Design tokens: ChronoMind product section, own urgency colors P1 High: - Added pre-work (domain, wireframes, design tokens) - Added CI/CD (GitHub Actions + Vercel auto-deploy) - Added analytics (platform-service telemetry) - Added onboarding (3-step walkthrough) - Added privacy policy + terms of service - Added web accessibility (WCAG 2.1 AA) - Added timer accuracy tests + offline resilience strategy - Added feedback mechanism - Timer engine: clarified rAF (UI) + setInterval (SW) dual architecture - Neurodivergent mode: default UX, not toggle (Compact mode for power users) - Phase 3: macOS deferred to Phase 4, iPad layout added P2 Medium: - Calendar sync: two-way → one-way (read-only) - Event countdown timer added to Phase 2 - Timer export/import added to Phase 2 - iOS waitlist added to Phase 2 - Data export/deletion added to Phase 4 - NL extraction upgrade path added to Phase 4 - Body doubling deferred to v3 New appendices: Cost Estimation, Common Platform Reusability, Key Decisions Updated: success metrics (aligned with PRD), risk register (+4 new risks) V2 review doc marked as APPLIED (audit trail) --- docs/roadmap-v2-review.md | 4 +- docs/roadmap.md | 267 ++++++++++++++++++++++++++++++-------- 2 files changed, 218 insertions(+), 53 deletions(-) diff --git a/docs/roadmap-v2-review.md b/docs/roadmap-v2-review.md index de5fb5f..a38a069 100644 --- a/docs/roadmap-v2-review.md +++ b/docs/roadmap-v2-review.md @@ -2,8 +2,8 @@ > **Purpose:** Systematic review of `roadmap.md` (v1) identifying bugs, gaps, missing details, and opportunities to leverage the `learning_ai_common_plat` shared ecosystem. > **Date:** February 2026 -> **Status:** PENDING USER REVIEW — do not implement until signed off. -> **Action:** Review each finding, then this doc becomes the implementation guide for roadmap v2. +> **Status:** ✅ APPLIED — All findings incorporated into `roadmap.md` v2.0. This doc is now an audit trail. +> **Action:** No further action needed. See `roadmap.md` for the implementation-ready version. --- diff --git a/docs/roadmap.md b/docs/roadmap.md index 67bf70c..1d8b0f7 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,9 +1,14 @@ # 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](roadmap-v2-review.md) audit) > **Created:** February 2026 -> **See also:** [PRD.md](PRD.md) | [INDUSTRY_RESEARCH.md](INDUSTRY_RESEARCH.md) +> **License:** Closed-source app; timer engine library open-source (TBD license) +> **See also:** [PRD.md](PRD.md) | [INDUSTRY_RESEARCH.md](INDUSTRY_RESEARCH.md) | [roadmap-v2-review.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`. --- @@ -46,8 +51,8 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat │ UI: Jetpack Compose │ │ Watch: Wear OS + Glance widgets │ │ │ -│ Shared: Cloud Sync API (optional, E2E encrypted) │ -│ Analytics: Plausible / PostHog (privacy-first) │ +│ Shared: Platform-service (Fastify, port 4003) — Cosmos DB sync │ +│ Analytics: Platform-service telemetry / Plausible (privacy-first) │ └──────────────────────────────────────────────────────────────────────────┘ ``` @@ -60,23 +65,35 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat ### 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** - [ ] `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/` + - [ ] GitHub Actions CI: lint + typecheck + vitest on PR + - [ ] Auto-deploy to Vercel on `main` push + - [ ] Analytics: platform-service telemetry module (or Plausible as lightweight fallback) + - [ ] Track: page views, timer created, timer completed, cascade fired, Pomodoro completed, PWA installed - [ ] **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 + - [ ] `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 - [ ] **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) + - [ ] Cascade presets (aligned with PRD): Aggressive (4h, 3h, 2h, 90m, 1h, 30m, 15m, 5m, 1m), Standard (2h, 1h, 30m, 15m, 5m), Light (1h, 15m, 5m), Minimal (15m), None (fire only), Custom (user-defined) - [ ] Custom cascade builder (user picks intervals) - [ ] Cascade scheduler: calculate all warning timestamps from target time - [ ] Cascade state tracking: which warnings have fired @@ -172,6 +189,34 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] "Try it now" button → app dashboard (no signup needed) - [ ] Social proof section (placeholder for future testimonials) - [ ] Footer: links, GitHub, privacy + - [ ] Privacy policy page (`/privacy`) — required before any data collection or App Store submission + - [ ] Terms of service page (`/terms`) + +- [ ] **First-run onboarding** + - [ ] 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** + - [ ] Feedback button in app (opens email or form) + - [ ] Bug report button with auto-attached browser info + +- [ ] **Web accessibility (WCAG 2.1 AA)** + - [ ] Keyboard navigation works for all flows + - [ ] Screen reader tested (NVDA/VoiceOver) on timeline and timer creation + - [ ] Focus indicators on all interactive elements + - [ ] Sufficient color contrast for all urgency levels + +- [ ] **Timer accuracy tests** + - [ ] Timing accuracy: create timer for T+5s, verify fires within 100ms tolerance + - [ ] 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 @@ -183,8 +228,12 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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 +- [ ] Deployed to Vercel with custom domain +- [ ] CI/CD pipeline running (GitHub Actions + Vercel auto-deploy) +- [ ] Analytics tracking timer creation and cascade engagement +- [ ] WCAG 2.1 AA: keyboard nav + screen reader tested +- [ ] Privacy policy published at `/privacy` +- [ ] 5 beta testers using it daily (measured via analytics) --- @@ -287,7 +336,7 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] Conflict detection: warn if imported event overlaps existing timer - [ ] Map calendar event priority to urgency level -- [ ] **Neurodivergent mode** +- [ ] **Neurodivergent-friendly design (DEFAULT UX, not a toggle)** - [ ] Visual countdown ring (`components/CountdownRing.tsx`) - [ ] Large, animated circular countdown (inspired by Time Timer) - [ ] Color transitions: green → yellow → orange → red as time decreases @@ -295,8 +344,8 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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) + - [ ] Body doubling placeholder: "Focus with others" room (v3 feature, show coming soon) + - [ ] Toggle in settings: "Compact mode" for power users who want dense UI (the DEFAULT is already neurodivergent-friendly per PRD decision #7) - [ ] **Prep time intelligence** - [ ] Per-timer: "I need X minutes to prepare" @@ -310,6 +359,22 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] Suggestion shown as dismissable card on dashboard - [ ] Accept → auto-adjusts recurring timer +- [ ] **Event countdown timer** + - [ ] Days/hours until a future date with milestone warnings (30 days, 7 days, 1 day, etc.) + - [ ] Timer type `event` in data model (matching PRD feature #26) + - [ ] Visual: large countdown display with milestone progress bar + - [ ] Use cases: "132 days until wedding", "47 days until vacation" + +- [ ] **Timer export / import (local backup)** + - [ ] "Export timers" → JSON download of all timers, routines, stats + - [ ] "Import timers" → upload JSON to restore + - [ ] Warning: "Your timers are stored locally. Export regularly or enable cloud sync (coming in v1.1)." + +- [ ] **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/(app)/history/`)** - [ ] Searchable log of all past timers - [ ] Filter by category, urgency, date range @@ -331,18 +396,19 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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 +- [ ] Neurodivergent mode is default and noticeably gentler than previous - [ ] All E2E tests pass in CI - [ ] 25+ beta testers, 3+ using routines daily -- [ ] App Store / ProductHunt submission prepared +- [ ] ProductHunt submission prepared (web) — App Store prep moved to Phase 3 --- ## 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. +> **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](PRD.md). +> **Note:** This phase is 4 weeks, not 3 as PRD states. PRD phases section should be updated to match. ### Week 6: iOS App Foundation @@ -436,15 +502,9 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] App Intents framework for iOS 17+ - [ ] Shortcuts app integration -### Week 8: macOS + AI Reschedule +### Week 8: AI Reschedule + Gamification -- [ ] **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 +> **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 @@ -459,7 +519,12 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] Weekly summary card (shareable image — key for viral growth) - [ ] Gentle celebration animations (confetti for streak milestones, not obnoxious) -### Week 9: Polish + TestFlight +### 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+) - [ ] **Cross-device continuity** - [ ] Handoff: start timer on Mac, see it on iPhone and Watch @@ -483,34 +548,44 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] External beta: 100 testers via TestFlight link - [ ] Crash reporting: built-in MetricKit - [ ] Feedback form in Settings + - [ ] 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 -- [ ] 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) +- [ ] 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:** Calendar sync, location awareness, sleep integration, and viral growth mechanics. +> **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: Calendar + Location +### 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 - [ ] Apple Calendar (EventKit) read access - [ ] Outlook Calendar (Microsoft Graph API) integration - - [ ] Two-way sync: imported events become timers with auto-cascade + - [ ] One-way sync: imported events become timers with auto-cascade (read-only — ChronoMind does NOT write back to calendars) - [ ] 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 @@ -549,14 +624,27 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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 +- [ ] **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 - - [ ] Web: sync via authenticated API (JWT + encrypted payload) + - [ ] **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 + - [ ] "Delete my account" → wipe all cloud data, revoke tokens + - [ ] 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** @@ -607,10 +695,12 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat ### Phase 4 Exit Criteria -- [ ] Calendar sync works with Google, Apple, Outlook calendars +- [ ] macOS menu bar app works on macOS 14+ (deferred from Phase 3) +- [ ] Calendar sync works with Google, Apple, Outlook calendars (one-way) - [ ] Location triggers fire reliably (iOS geofencing) - [ ] Travel time estimates adjust pre-warning cascade - [ ] Sleep data integration working via HealthKit +- [ ] Data export and account deletion functional - [ ] Weekly summary card shareable to 3+ social platforms - [ ] Shareable timer links work (web + iOS universal link) - [ ] ProductHunt page live, launch scheduled @@ -680,13 +770,14 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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 +- [ ] **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 - - [ ] Account creation: email + password or Apple/Google Sign-In + - [ ] 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 @@ -699,12 +790,9 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat - [ ] 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) +- [ ] **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 @@ -768,10 +856,13 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat ### Metrics That Matter -| Metric | MVP Target | v1 Target | v2 Target | -|--------|-----------|-----------|-----------| -| **MAU** | 50 | 1,000 | 5,000 | -| **DAU/MAU ratio** | > 40% | > 50% | > 50% | +| 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% | @@ -780,6 +871,7 @@ ChronoMind ships in **5 phases over ~6 months**, from web MVP to full cross-plat | **Pro conversion** | — | > 3% | > 5% | | **Streak > 7 days** | — | > 15% of users | > 25% | | **Shared summary** | — | > 10% weekly | > 20% | +| **Snooze rate** | < 40% | < 30% | < 25% | ### Viral Growth Loops @@ -851,8 +943,12 @@ Family ($5.99/mo): Everything in Pro + shared timers (6 members), | 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 | +| 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 | --- @@ -877,8 +973,77 @@ Family ($5.99/mo): Everything in Pro + shared timers (6 members), |----------|-----------|--------------|---------|---------------| | **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 | +| **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** | TBD (Fastify or Cloudflare Workers) | JWT auth, E2E encryption | Cosmos DB or D1 | — | +| **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.