diff --git a/docs/roadmap-v2-review.md b/docs/roadmap-v2-review.md new file mode 100644 index 0000000..240a91f --- /dev/null +++ b/docs/roadmap-v2-review.md @@ -0,0 +1,581 @@ +# ChronoMind — Roadmap V2 Review + +> **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. + +--- + +## Table of Contents + +1. [Common Platform Reusability Audit](#1-common-platform-reusability-audit) +2. [Bugs & Errors in Roadmap v1](#2-bugs--errors-in-roadmap-v1) +3. [Architectural Gaps](#3-architectural-gaps) +4. [Missing Features & Details](#4-missing-features--details) +5. [Timeline Realism Check](#5-timeline-realism-check) +6. [Security & Privacy Gaps](#6-security--privacy-gaps) +7. [Testing & Quality Gaps](#7-testing--quality-gaps) +8. [Design System Gap](#8-design-system-gap) +9. [DevOps & Infrastructure Gaps](#9-devops--infrastructure-gaps) +10. [Recommendations Summary](#10-recommendations-summary) + +--- + +## 1. Common Platform Reusability Audit + +The `learning_ai_common_plat` repo contains **13 shared packages** and a **platform-service** (25 modules, 621 tests) that ChronoMind can leverage directly for its cloud/backend needs. The roadmap v1 treated ChronoMind as a fully standalone app with "TBD" backend — this is a significant missed opportunity. + +### 1.1 Packages Directly Reusable + +| Package | What It Does | ChronoMind Use Case | Phase | +|---------|-------------|---------------------|-------| +| **@bytelyst/auth** | JWT (jose), password hashing (bcryptjs) | User accounts, Pro/Family auth | 4-5 | +| **@bytelyst/react-auth** | React auth context factory (provider + hook) | Web dashboard auth for Pro users | 4-5 | +| **@bytelyst/api-client** | Configurable fetch wrapper with token injection | Web → sync API calls, shareable timer API | 4-5 | +| **@bytelyst/config** | Zod env loader, product identity, AKV resolver | Config management, `productId: "chronomind"` | 4-5 | +| **@bytelyst/cosmos** | Azure Cosmos DB singleton + container registry | Cloud sync storage, shared timers, user accounts | 4-5 | +| **@bytelyst/errors** | Typed HTTP errors (400-429) | Consistent error handling in sync API | 4-5 | +| **@bytelyst/logger** | Structured pino-based logging | Server-side logging | 4-5 | +| **@bytelyst/design-tokens** | JSON → CSS/TS/Kotlin/Swift token generator | Shared design system across web + native | 1-3 | +| **@bytelyst/monitoring** | Health-check utilities | Sync API health endpoint | 5 | +| **@bytelyst/blob** | Azure Blob Storage + SAS tokens | Custom alarm sound uploads (Pro feature) | 5 | +| **@bytelyst/testing** | Shared test mocks, Fastify inject helpers | Backend test infrastructure | 4-5 | +| **@bytelyst/fastify-core** | `createServiceApp()` + `startService()` | If sync API is Fastify (not Cloudflare Workers) | 5 | + +### 1.2 Platform-Service Modules Reusable + +| Module | What It Does | ChronoMind Use Case | +|--------|-------------|---------------------| +| **auth** | JWT issue/verify, login/register, SSO | User accounts for Pro/Family | +| **subscriptions** | Subscription CRUD, tier management | Pro + Family tier management | +| **plans** | Plan definitions (free, pro, family) | Plan enforcement | +| **stripe** | Stripe webhooks, checkout sessions | Web payment processing | +| **licenses** | License key generation/validation | Alternative to Stripe for one-time purchases | +| **usage** | Usage tracking per user per day | Timer/sync usage limits for free tier | +| **settings** | Per-user global settings + device overrides | User preferences sync | +| **notifications** | Notification templates + delivery | Push notification delivery for shared timers | +| **invitations** | Invite-by-link with codes | Household/family invitations | +| **referrals** | Referral tracking + reward distribution | Referral program ("invite friend → 1 month Pro") | +| **flags** | Feature flags with FNV-1a rollout | Gradual feature rollout (neurodivergent mode, AI reschedule) | +| **audit** | Audit log for admin actions | Admin visibility into shared timer abuse | +| **telemetry** | Client event ingest + admin query | App analytics (timer created, cascade fired, etc.) | +| **waitlist** | Pre-launch signups | Pre-launch waitlist for iOS/Android | +| **public** | Public endpoints (no auth) | Public shared timer viewing | +| **ratelimit** | IP + user rate limiting | Sync API abuse prevention | +| **products** | Multi-product registry | Register ChronoMind as a product alongside LysnrAI/MindLyst | + +### 1.3 What This Means for the Roadmap + +**Gap G-01:** Roadmap v1 line 884 says `Sync API: TBD (Fastify or Cloudflare Workers)`. This should NOT be TBD — the answer is **platform-service on Fastify**, which already has auth, subscriptions, stripe, invitations, referrals, usage tracking, settings, feature flags, rate limiting, and telemetry. Building a separate sync API from scratch would duplicate thousands of lines of tested code. + +**Recommendation:** Register ChronoMind as a new product in platform-service (`productId: "chronomind"`). Add ChronoMind-specific modules (timers, routines, shared-timers) to platform-service. Reuse everything else as-is. + +**New modules needed in platform-service for ChronoMind:** + +| Module | Purpose | Cosmos Container | +|--------|---------|-----------------| +| `timers` | Timer CRUD + sync | `timers` (pk: `productId:userId`) | +| `routines` | Routine CRUD + templates | `routines` (pk: `productId:userId`) | +| `shared-timers` | Household shared timers | `shared_timers` (pk: `productId:householdId`) | +| `households` | Household group management | `households` (pk: `productId:householdId`) | + +--- + +## 2. Bugs & Errors in Roadmap v1 + +### B-01: Sync API "TBD" — Decision Gap (Critical) + +- **Location:** Line 884, Appendix Tech Stack +- **Issue:** `Sync API: TBD (Fastify or Cloudflare Workers)` — this is the most critical architectural decision in the roadmap and it's left unresolved. +- **Impact:** Cannot plan Phase 4-5 properly without knowing the backend stack. +- **Fix:** Use platform-service (Fastify) in `learning_ai_common_plat`. See §1.3 above. + +### B-02: Phase 4 Cloud Sync Contradicts Phase 5 Cloud Sync + +- **Location:** Phase 4 (line 552-558) and Phase 5 (line 683-689) +- **Issue:** Phase 4 says "E2E encrypted sync via CloudKit (Apple) **or** custom API" and Phase 5 says "Cross-platform cloud sync — Sync API: REST endpoints." These are different systems. Which comes first? Is CloudKit used at all? +- **Impact:** Building CloudKit sync in Phase 4 then replacing it with a REST API in Phase 5 is wasted work. +- **Fix:** Pick one path. Recommendation: iCloud/CloudKit for Apple-only sync (Phase 3, via App Groups + CloudKit), then platform-service REST API for cross-platform sync (Phase 5). Phase 4 cloud sync should explicitly say "iCloud only — cross-platform deferred to Phase 5." + +### B-03: macOS NSUserNotificationCenter is Deprecated + +- **Location:** Line 881, Appendix Tech Stack +- **Issue:** `NSUserNotificationCenter` has been deprecated since macOS 11. macOS uses `UNUserNotificationCenter` now (same as iOS). +- **Fix:** Replace `NSUserNotificationCenter` with `UNUserNotificationCenter` in the macOS row. + +### B-04: ClockKit Listed for watchOS — Deprecated + +- **Location:** Line 880, Appendix Tech Stack +- **Issue:** `ClockKit` is deprecated as of watchOS 9. All complications should use `WidgetKit` (already mentioned in Phase 3 text, but the appendix still lists ClockKit). +- **Fix:** Remove `ClockKit` from the watchOS tech stack row. Replace with `WidgetKit` only. + +### B-05: "Two-way sync" for Calendar is Overambitious + +- **Location:** Phase 4, line 513 +- **Issue:** "Two-way sync: imported events become timers with auto-cascade" — writing back to Google/Apple/Outlook calendars is extremely complex, fragile, and likely unwanted (users don't want timers appearing as calendar events). +- **Fix:** Change to one-way: calendar → ChronoMind. Users create timers in ChronoMind; calendar events are read-only. + +### B-06: Week 2 Exit Criteria Mentions "5 beta testers" — No User Account System Exists + +- **Location:** Phase 1, line 187 +- **Issue:** "5 beta testers using it daily" — but there's no user accounts, no analytics, no way to measure this in Phase 1. +- **Fix:** Add analytics (Plausible or PostHog) in Phase 1 scaffold. It's mentioned in the architecture diagram (line 50) but never appears in any Phase 1 checklist item. + +### B-07: Phase 2 Exit Says "App Store submission prepared" — App Doesn't Exist Yet + +- **Location:** Phase 2, line 337 +- **Issue:** "App Store / ProductHunt submission prepared" — but the iOS app isn't built until Phase 3. +- **Fix:** Change to "ProductHunt submission prepared (web)" — App Store prep belongs in Phase 3. + +--- + +## 3. Architectural Gaps + +### G-02: No `productId` Strategy for Multi-Product Ecosystem + +- **Issue:** The ByteLyst ecosystem requires every Cosmos document to include `productId`. ChronoMind needs to be registered as a product (`productId: "chronomind"`) in platform-service's products module. +- **Impact:** Without this, ChronoMind data will collide with LysnrAI/MindLyst data in shared Cosmos containers. +- **Fix:** Add a Phase 4 task: "Register ChronoMind as product in platform-service (productId: chronomind, displayName: ChronoMind, licensePrefix: CHRONO)." + +### G-03: No Data Model Specification for Cloud Sync + +- **Issue:** The roadmap mentions cloud sync in Phase 4 and 5 but never defines the data schema for synced entities. What fields does a synced timer have? What about conflict resolution specifics? +- **Fix:** Add a data model appendix or reference the PRD's data model section. Specify: + - Timer sync schema (all fields from web IndexedDB → Cosmos) + - Routine sync schema + - Conflict resolution: field-level merge vs document-level last-write-wins + - Sync metadata: `syncedAt`, `deviceId`, `version` fields + +### G-04: No Onboarding Flow + +- **Issue:** Phase 1 has a landing page with "Try it now" but no onboarding experience once users enter the app. First-time users need guidance to create their first timer, understand cascades, and set urgency levels. +- **Fix:** Add to Phase 1 Week 2: + - 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 + +### G-05: No Error Handling / Offline Resilience Strategy for Web + +- **Issue:** PWA is mentioned but there's no strategy for: + - What happens when a timer fires while offline? + - What happens when Service Worker is killed by the browser? + - What's the fallback when IndexedDB is full? + - How do notifications work if the tab is closed? +- **Fix:** Add to Phase 1: + - Document SW lifecycle: timers must survive SW termination → use IndexedDB timestamps + SW `periodicsync` or `alarm` events + - 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 + +### G-06: No Migration Strategy Between Phases + +- **Issue:** Phase 1 stores everything in IndexedDB. Phase 4 introduces cloud sync. How does data migrate? What happens to offline-only users? +- **Fix:** Add migration plan: + - Phase 4: "Import from local" button — one-time upload of IndexedDB data to cloud + - Cloud sync is always opt-in; local-only remains fully supported + - Version field in IndexedDB schema to handle schema migrations between phases + +### G-07: Shared Timer Architecture Not Defined + +- **Issue:** Phase 5 mentions shared timers with "real-time sync" but doesn't specify the architecture. WebSocket? Server-Sent Events? Polling? +- **Fix:** Add architecture decision: + - Real-time: WebSocket via platform-service (or SSE for simplicity) + - Fallback: polling every 30 seconds for web, push notifications for iOS/Android + - Cosmos change feed for server-side event propagation + +--- + +## 4. Missing Features & Details + +### M-01: No Privacy Policy / Terms of Service + +- **Issue:** Phase 1 landing page lists "Footer: links, GitHub, privacy" but no task to actually write the privacy policy. This is required before any data collection or App Store submission. +- **Fix:** Add to Phase 2: "Write privacy policy and terms of service. Host at /privacy and /terms." + +### M-02: No Data Export / Account Deletion + +- **Issue:** GDPR and App Store require data export and account deletion capabilities. Not mentioned anywhere. +- **Fix:** Add to Phase 4: + - "Export all my data" → JSON download of all timers, routines, stats + - "Delete my account" → wipe all cloud data, revoke tokens + - These are App Store requirements since 2022. + +### M-03: No Settings Sync Between Web and Native + +- **Issue:** Phase 1 stores settings in localStorage. Phase 3 uses SwiftUI `@AppStorage`. Phase 5 adds Android DataStore. There's no plan to sync settings across platforms. +- **Fix:** Phase 4 cloud sync should explicitly include user preferences sync. Use platform-service's existing `settings` module. + +### M-04: No Waitlist / Pre-Launch for iOS + +- **Issue:** Phase 3 goes straight to TestFlight with 100 testers. No mechanism to collect interest before Phase 3. +- **Fix:** Add to Phase 2: + - Waitlist signup on web landing page ("Get notified when iOS launches") + - Use platform-service's `waitlist` module (already exists) + - Email collection for launch announcement + +### M-05: No Routine Template Marketplace / Sharing + +- **Issue:** Phase 2 has routine templates (Morning, Evening, Cooking) as hardcoded presets. Phase 4 has shareable timers. But there's no mechanism to share or discover routine templates. +- **Fix:** Add to Phase 4: + - "Share routine as template" → generates a link + - "Browse community templates" → curated list on web + - Platform-service `public` module can serve public templates + +### M-06: No iPad-Specific Layout + +- **Issue:** Phase 3 targets iOS but never mentions iPad. iPadOS is a significant market for productivity apps. +- **Fix:** Add to Phase 3 Week 9: + - iPad sidebar navigation (UISplitViewController equivalent in SwiftUI) + - Wider timeline with side panel for timer detail + - Stage Manager / multiple window support (iPadOS 16+) + +### M-07: No Accessibility Testing in Phase 1-2 + +- **Issue:** Accessibility is only mentioned in Phase 3 (Week 9) for native apps. Web PWA also needs accessibility. +- **Fix:** Add to Phase 1 exit criteria: + - WCAG 2.1 AA compliance for all interactive elements + - Keyboard navigation works for all flows + - Screen reader (NVDA/VoiceOver) tested on timeline and timer creation + +### M-08: No Analytics Implementation Details + +- **Issue:** Architecture diagram mentions "Plausible / PostHog" but no checklist item installs or configures analytics. +- **Fix:** Add to Phase 1 Week 1: + - Install Plausible (privacy-first, no cookies) or PostHog (self-hosted option) + - Track: page views, timer created, timer completed, cascade fired, Pomodoro completed, PWA installed + - Dashboard for monitoring key metrics + - Or: use platform-service telemetry module (`@bytelyst/telemetry`) + +### M-09: No CI/CD Pipeline + +- **Issue:** The roadmap never mentions CI/CD. No GitHub Actions, no automated testing, no deployment pipeline. +- **Fix:** Add to Phase 1 Week 1: + - GitHub Actions: lint + typecheck + vitest on PR + - Auto-deploy to Vercel on `main` push + - Phase 3: Xcode Cloud or Fastlane for TestFlight builds + - Phase 5: Gradle CI for Android builds + +### M-10: No Feedback Collection Mechanism for Web + +- **Issue:** Phase 3 has "Feedback form in Settings" for iOS TestFlight. Web MVP has no feedback mechanism. +- **Fix:** Add to Phase 1 Week 2: + - Feedback button in web app (opens email or form) + - Or: integrate with platform-service's notification/feedback pipeline + - Bug report button with auto-attached browser info + +--- + +## 5. Timeline Realism Check + +### T-01: Phase 1 (2 Weeks) is Aggressive but Achievable + +- Week 1: scaffold + timer engine + cascade + urgency + timeline + create flow + clock = **7 major features** +- Week 2: notifications + sounds + tab title + alarm overlay + Pomodoro + theme + PWA + shortcuts + landing = **9 major features** +- **Assessment:** Tight but doable for a solo developer if scope is strictly enforced. The timer engine and cascade are the hard parts; UI is mostly shadcn/ui components. +- **Risk:** Serwist (PWA) setup can be tricky. Budget 0.5-1 day just for Service Worker debugging. + +### T-02: Phase 3 (4 Weeks for iOS + Watch + Mac) is Very Aggressive + +- Week 6: Xcode setup + Swift port + data models + 7 screens + notifications + haptics +- Week 7: Watch app + 4 complications + Live Activities + Dynamic Island + widgets + Siri +- Week 8: macOS menu bar + AI reschedule + gamification +- Week 9: Continuity + accessibility + tests + TestFlight +- **Assessment:** This is the most compressed phase. Apple Watch complications + Live Activities alone can eat a full week of debugging. Siri Shortcuts with App Intents is another 2-3 days. +- **Recommendation:** Either extend Phase 3 to 5-6 weeks, or defer macOS and Siri to Phase 4. Prioritize: iOS app (Week 6-7) → Watch + Widgets (Week 8) → TestFlight (Week 9). macOS menu bar can wait. + +### T-03: Phase 5 (8 Weeks) Has Room for Slip + +- This is the longest phase and includes the most ambitious features (Android, Wear OS, shared timers, body doubling, API/webhooks, smart home, monetization). +- **Assessment:** Realistic if shared timers are simplified (no real-time, polling-based sync) and body doubling is deferred. +- **Recommendation:** Body doubling (line 702-707) should be labeled as "stretch goal" or "v3", not Phase 5. + +--- + +## 6. Security & Privacy Gaps + +### S-01: No Auth for Shared Timer Links + +- **Issue:** Phase 4 says "Create a timer and share link: chronom.ind/t/abc123". But who can access this? Is it public? Can anyone add it to their account? +- **Fix:** Define access levels: + - Public link: anyone can view timer details (read-only) + - Authenticated link: only registered users can add to their timers + - Private link: only invited household members can see + +### S-02: No Abuse Prevention for Shared Timers + +- **Issue:** Shared timers with "real-time sync" and "up to 6 members" need protection against abuse (spam timers, offensive labels, etc.). +- **Fix:** Add: + - Rate limit on timer creation per household + - Content filtering on timer labels (basic profanity filter) + - Household admin can delete any shared timer + - Report mechanism + +### S-03: No Secret Management for Web App + +- **Issue:** Phase 4-5 requires API keys (Stripe, Google Calendar OAuth, etc.) but no mention of how secrets are managed for the web deployment. +- **Fix:** Use platform-service's existing AKV integration. Web app server-side routes (Next.js API routes) access secrets via `@bytelyst/config` with `resolveKeyVaultSecrets()`, same pattern as other dashboards. + +### S-04: E2E Encryption Not Specified + +- **Issue:** "E2E encrypted sync" is mentioned twice (Phase 4 line 553, Phase 5 line 686) but the encryption scheme is never specified. +- **Fix:** Add specification: + - Client generates AES-256 key on first sync + - Key is derived from user's password (PBKDF2) — never sent to server + - Timer data encrypted client-side before upload + - Server stores encrypted blobs — cannot read timer content + - Key recovery: user must remember password or loses data (acceptable for a timer app) + - **Alternative:** Skip E2E encryption. Timer data is not particularly sensitive. TLS in transit + encrypted at rest in Cosmos is sufficient. E2E adds significant complexity for minimal benefit in a timer app. + +--- + +## 7. Testing & Quality Gaps + +### Q-01: No Test Strategy for Timer Accuracy + +- **Issue:** The core value prop is timers firing at the right time. But no test verifies timing accuracy. +- **Fix:** Add to Phase 1: + - Timing accuracy tests: create timer for T+5s, verify it fires within 100ms tolerance + - Service Worker notification timing tests + - Stress test: 50 concurrent timers with cascades → all fire correctly + +### Q-02: No Performance Budget + +- **Issue:** "Page load < 2 seconds" and "Lighthouse PWA > 90" are mentioned but no ongoing performance budget. +- **Fix:** Add to Phase 1: + - Bundle size budget: < 200KB JS (gzipped) + - Lighthouse CI in GitHub Actions (fail if score drops below 85) + - Core Web Vitals monitoring via Plausible/PostHog + +### Q-03: No Cross-Browser Testing Matrix + +- **Issue:** "Chrome, Safari, Firefox" mentioned in exit criteria but no systematic test matrix. +- **Fix:** Add test matrix: + - Chrome 120+ (desktop + Android) + - Safari 17+ (macOS + iOS — PWA behavior differs significantly) + - Firefox 120+ (desktop) + - Edge 120+ (Chromium-based, should work) + - Samsung Internet (large Android market share) + +### Q-04: No Regression Test for Cascade Timing After DST + +- **Issue:** Daylight Saving Time causes timers to shift. The recurrence module mentions DST in tests but cascades don't. +- **Fix:** Add cascade-specific DST test: "Timer at 2:30 AM on DST day — cascade fires correctly despite time jump." + +--- + +## 8. Design System Gap + +### D-01: No Shared Design Tokens Usage + +- **Issue:** The roadmap mentions "Dark + light theme" with "CSS custom properties + Tailwind dark mode" but doesn't leverage `@bytelyst/design-tokens`. The design-tokens package already has a complete color palette, spacing scale, typography, and generates CSS + TypeScript + Swift + Kotlin outputs. +- **Impact:** ChronoMind will have an inconsistent design language from the rest of the ByteLyst ecosystem. +- **Fix:** Add to Phase 1 scaffold: + - Extend `bytelyst.tokens.json` with ChronoMind-specific tokens (or create `chronomind.tokens.json`) + - Use the `generate.ts` script to produce `tokens.css` (web), `ChronoMindTokens.swift` (iOS), `ChronoMindTokens.kt` (Android) + - Map urgency levels to specific colors from the token palette + - This gives automatic design consistency across all platforms + +### D-02: No Design Mockups / Wireframes Phase + +- **Issue:** The roadmap jumps straight to building components without any design phase. No mention of Figma, wireframes, or design review. +- **Fix:** Add to Phase 1 Week 1 (before coding): + - Wireframe: timeline, create timer, Pomodoro, alarm overlay (low-fi sketches or Figma) + - Define urgency level color mapping (Critical=red, Important=orange, Standard=blue, Gentle=green, Passive=gray) + - Define typography scale (heading, body, caption, countdown digits) + - This doesn't need to be elaborate — 1 day of wireframing saves a week of UI rework + +--- + +## 9. DevOps & Infrastructure Gaps + +### I-01: No Domain / DNS Planning + +- **Issue:** The roadmap mentions "custom domain" for deployment (Phase 1 exit) and "chronom.ind/t/abc123" for shared timer links but never plans for domain acquisition. +- **Fix:** Add to Phase 1 pre-work: + - Register domain: `chronomind.app` or `chronomind.io` or `chronom.ind` + - Set up DNS for web deployment (Vercel/Netlify) + - Set up Universal Links (Apple) and App Links (Android) for deep linking + +### I-02: No Monitoring / Alerting for Cloud Services + +- **Issue:** Phase 5 mentions "Sync API < 200ms p99" but no monitoring infrastructure to measure this. +- **Fix:** Add to Phase 5: + - Use `@bytelyst/monitoring` for health checks + - Grafana dashboard (already exists in common-plat monitoring service) + - Alert on: sync API latency > 500ms, error rate > 1%, Cosmos RU consumption + +### I-03: No Cost Estimation + +- **Issue:** The roadmap mentions Cosmos DB, Azure Blob, Stripe, Plausible, domain, Apple Developer ($99/yr), Google Play ($25 one-time) — but no cost estimate. +- **Fix:** Add cost appendix: + - Vercel Pro: $20/mo (or free tier for hobby) + - Cosmos DB: ~$25/mo (400 RU/s, shared with other products) + - Apple Developer: $99/yr + - Google Play: $25 one-time + - Domain: ~$15/yr + - Plausible: $9/mo (or self-hosted free) + - **Total pre-revenue: ~$50-70/mo + $124 one-time** + +### I-04: No Backup / Disaster Recovery Plan + +- **Issue:** User timer data is stored in IndexedDB (local, no backup) for Phases 1-3. If a user clears browser data, all timers are lost. +- **Fix:** Add to Phase 2: + - "Export timers" → JSON download (manual backup) + - "Import timers" → upload JSON to restore + - Show warning: "Your timers are stored locally. Export regularly or enable cloud sync (coming in v1.1)." + +--- + +## 10. Recommendations Summary + +### Critical (Must Fix Before Implementation) + +| # | Finding | Fix | Priority | +|---|---------|-----|----------| +| G-01 | Sync API "TBD" | Use platform-service in common-plat | **P0** | +| B-01 | Sync API decision gap | Fastify on platform-service, not Cloudflare Workers | **P0** | +| G-02 | No productId strategy | Register `chronomind` in products module | **P0** | +| D-01 | No design tokens integration | Use `@bytelyst/design-tokens` | **P0** | +| B-02 | Phase 4/5 cloud sync contradiction | iCloud in Phase 3, REST API in Phase 5 | **P0** | + +### High (Should Fix Before Implementation) + +| # | Finding | Fix | Priority | +|---|---------|-----|----------| +| G-04 | No onboarding flow | Add first-run walkthrough to Phase 1 | **P1** | +| G-05 | No offline resilience strategy | Document SW lifecycle, fallback behaviors | **P1** | +| M-09 | No CI/CD pipeline | GitHub Actions + Vercel auto-deploy | **P1** | +| M-08 | No analytics implementation | Add Plausible/PostHog in Phase 1 | **P1** | +| T-02 | Phase 3 too compressed | Extend to 5-6 weeks or defer macOS | **P1** | +| B-03 | NSUserNotificationCenter deprecated | Use UNUserNotificationCenter | **P1** | +| B-04 | ClockKit deprecated | Use WidgetKit only | **P1** | +| M-01 | No privacy policy | Write before any data collection | **P1** | +| Q-01 | No timer accuracy tests | Add timing tolerance tests | **P1** | +| I-01 | No domain planning | Register domain pre-Phase 1 | **P1** | + +### Medium (Can Address During Implementation) + +| # | Finding | Fix | Priority | +|---|---------|-----|----------| +| B-05 | Two-way calendar sync | Change to one-way (read-only) | **P2** | +| B-06 | "5 beta testers" unmeasurable | Add analytics first | **P2** | +| B-07 | App Store prep in Phase 2 | Move to Phase 3 | **P2** | +| G-03 | No cloud data model spec | Add data model appendix | **P2** | +| G-06 | No migration strategy | Add "import from local" flow | **P2** | +| G-07 | Shared timer architecture undefined | Define WebSocket vs polling | **P2** | +| M-02 | No data export / deletion | Add to Phase 4 (App Store requirement) | **P2** | +| M-04 | No iOS waitlist | Use platform-service waitlist module | **P2** | +| M-06 | No iPad layout | Add to Phase 3 | **P2** | +| M-07 | No web accessibility testing | Add to Phase 1 | **P2** | +| M-10 | No web feedback mechanism | Add feedback button | **P2** | +| S-04 | E2E encryption not specified | TLS + at-rest encryption is sufficient | **P2** | +| D-02 | No wireframes phase | 1 day of wireframing pre-Phase 1 | **P2** | +| I-03 | No cost estimation | Add cost appendix | **P2** | +| I-04 | No backup plan | Add export/import in Phase 2 | **P2** | + +### Low (Stretch / Future) + +| # | Finding | Fix | Priority | +|---|---------|-----|----------| +| M-03 | No settings sync | Use platform-service settings module | **P3** | +| M-05 | No routine marketplace | Add community templates in Phase 4 | **P3** | +| S-01 | Shared timer link access levels | Define public/auth/private | **P3** | +| S-02 | Shared timer abuse prevention | Rate limiting + content filter | **P3** | +| T-03 | Body doubling ambitious | Defer to v3 | **P3** | +| Q-02 | No performance budget | Add Lighthouse CI | **P3** | +| Q-03 | No cross-browser matrix | Define test matrix | **P3** | +| Q-04 | No DST cascade test | Add regression test | **P3** | +| I-02 | No monitoring | Use @bytelyst/monitoring | **P3** | + +--- + +## Appendix A: Revised Architecture with Common Platform + +``` +learning_ai_clock/ # ChronoMind repo +├── web/ # Next.js 16 PWA (Track 1) +│ ├── src/ +│ │ ├── app/ # App Router pages +│ │ ├── components/ # React components +│ │ ├── lib/ +│ │ │ ├── timer-engine.ts # Core timer engine +│ │ │ ├── cascade.ts # Pre-warning cascade +│ │ │ ├── recurrence.ts # Recurrence rules +│ │ │ ├── urgency.ts # Urgency levels +│ │ │ ├── nl-parser.ts # NL time parsing (chrono-node) +│ │ │ ├── store.ts # Zustand + IndexedDB +│ │ │ ├── platform-client.ts # @bytelyst/api-client → platform-service +│ │ │ ├── auth.ts # @bytelyst/react-auth context +│ │ │ └── product-config.ts # @bytelyst/config (productId: chronomind) +│ │ └── styles/ # TailwindCSS + design tokens CSS +│ └── package.json # file: refs to @bytelyst/* packages +│ +├── apple/ # Xcode project (Track 2) +│ ├── Shared/ # Shared across iOS + watchOS + macOS +│ │ ├── TimerEngine/ # Swift port of timer-engine.ts +│ │ ├── Models/ # SwiftData models +│ │ ├── Notifications/ # UNUserNotificationCenter +│ │ ├── Sync/ # CloudKit + platform-service client +│ │ └── Theme/ # ChronoMindTokens.swift (generated) +│ ├── ChronoMind/ # iOS app target +│ ├── ChronoMindWatch/ # watchOS target +│ └── ChronoMindMac/ # macOS menu bar target +│ +├── android/ # Jetpack Compose (Track 3, Phase 5) +│ └── app/src/main/ +│ ├── TimerEngine/ # Kotlin port +│ ├── ui/ # Compose screens +│ └── theme/ # ChronoMindTokens.kt (generated) +│ +├── docs/ # Planning documents +│ ├── PRD.md +│ ├── INDUSTRY_RESEARCH.md +│ ├── roadmap.md # Roadmap v1 +│ └── roadmap-v2-review.md # This document +│ +└── (no backend — uses learning_ai_common_plat/services/platform-service) + +learning_ai_common_plat/ # Shared platform (sibling repo) +├── packages/ # @bytelyst/* consumed via file: refs +│ ├── auth/ # JWT + password → web auth +│ ├── react-auth/ # React context → web auth UI +│ ├── api-client/ # Fetch wrapper → web API calls +│ ├── config/ # Env + productId → web config +│ ├── cosmos/ # DB client → sync API storage +│ ├── design-tokens/ # Tokens → web CSS + Swift + Kotlin +│ └── ... +├── services/ +│ └── platform-service/ # Port 4003 — shared backend +│ └── src/modules/ +│ ├── auth/ # ← reuse for ChronoMind accounts +│ ├── subscriptions/ # ← reuse for Pro/Family tiers +│ ├── stripe/ # ← reuse for payments +│ ├── invitations/ # ← reuse for household invites +│ ├── referrals/ # ← reuse for referral program +│ ├── settings/ # ← reuse for user preferences +│ ├── flags/ # ← reuse for feature rollout +│ ├── telemetry/ # ← reuse for app analytics +│ ├── waitlist/ # ← reuse for pre-launch signups +│ ├── ratelimit/ # ← reuse for API protection +│ ├── usage/ # ← reuse for free tier limits +│ ├── timers/ # ← NEW: ChronoMind timer CRUD + sync +│ ├── routines/ # ← NEW: routine CRUD + templates +│ ├── shared-timers/ # ← NEW: household shared timers +│ └── households/ # ← NEW: household management +``` + +## Appendix B: Key Decisions Needed Before Implementation + +| # | Decision | Options | Recommendation | Notes | +|---|----------|---------|----------------|-------| +| 1 | **Backend stack** | Platform-service (Fastify) vs Cloudflare Workers vs new service | Platform-service | Reuses 20+ existing modules, zero new infrastructure | +| 2 | **Apple-only sync (Phase 3)** | CloudKit vs skip until Phase 5 | CloudKit for Phase 3, platform-service for Phase 5 | CloudKit is free and fast for Apple-only; cross-platform needs REST | +| 3 | **E2E encryption** | Full E2E vs TLS + at-rest | TLS + at-rest | Timer data isn't sensitive enough to justify E2E complexity | +| 4 | **Real-time shared timers** | WebSocket vs SSE vs polling | SSE (simpler than WS) with polling fallback | Full WebSocket is overkill for timer updates | +| 5 | **Design tokens** | Extend bytelyst.tokens.json vs separate file | Extend existing | Maintains ecosystem consistency | +| 6 | **Analytics** | Plausible vs PostHog vs platform-service telemetry | Platform-service telemetry (already built) | Free, self-hosted, integrated with admin dashboard | +| 7 | **Phase 3 scope** | iOS + Watch + Mac (4 weeks) vs iOS + Watch (4 weeks) + Mac later | Defer macOS to Phase 4 | 4 weeks for iOS + Watch + Live Activities is already aggressive | +| 8 | **Calendar sync direction** | Two-way vs one-way (read-only) | One-way (calendar → ChronoMind) | Two-way is fragile and likely unwanted | +| 9 | **Body doubling** | Phase 5 vs v3 | Defer to v3 | Experimental, requires real-time infrastructure | +| 10 | **Domain name** | chronomind.app vs chronomind.io vs other | Check availability, decide before Phase 1 | Needed for deployment + Universal Links |