1b148757af
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)
736 lines
45 KiB
Markdown
736 lines
45 KiB
Markdown
# 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:** ✅ 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.
|
|
|
|
---
|
|
|
|
## 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. [PRD ↔ Roadmap Cross-Reference Gaps](#10-prd--roadmap-cross-reference-gaps)
|
|
11. [Platform Dependencies & Blockers](#11-platform-dependencies--blockers)
|
|
12. [Recommendations Summary](#12-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/extraction** | `createExtractionClient()`, shared extraction types | Advanced NL parsing via extraction-service (LLM-powered entity extraction as upgrade path from chrono-node) | 2+ |
|
|
| **@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. PRD ↔ Roadmap Cross-Reference Gaps
|
|
|
|
Systematic comparison of `PRD.md` (v0.2) against `roadmap.md` (v1) revealed **12 inconsistencies** — several significant.
|
|
|
|
### X-01: Windows/Tauri Missing from Roadmap Entirely
|
|
|
|
- **PRD line 59:** `v2.0 | Windows | Tauri` is listed as a target platform.
|
|
- **Roadmap v1:** Phase 5 covers Android + Wear OS but never mentions Windows or Tauri.
|
|
- **Impact:** Either the PRD overpromises or the roadmap under-delivers. Windows/Tauri is a non-trivial addition.
|
|
- **Fix:** Either add a Phase 6 for Windows/Tauri, or remove it from the PRD and label it as "v3 / future" to match the roadmap's scope through v2.
|
|
|
|
### X-02: Event Countdown Timer Type Never Scheduled
|
|
|
|
- **PRD feature #26:** "Event countdowns — 132 days until wedding with milestone warnings" is listed as v1.0.
|
|
- **Roadmap v1:** No Phase 1 or 2 checklist item implements this timer type. The PRD data model includes `type: 'event'` but no roadmap task builds it.
|
|
- **Fix:** Add to Phase 2 Week 4: "Event countdown timer — days/hours until a future date with milestone warnings at configurable intervals (30 days, 7 days, 1 day, etc.)."
|
|
|
|
### X-03: Cascade Preset Names Don't Match
|
|
|
|
- **PRD (line 131-138):** Presets are `Aggressive`, `Standard`, `Light`, `Minimal`, `None`, `Custom`
|
|
- **Roadmap Phase 1 (line 79):** Presets are `Relaxed`, `Standard`, `Tight`, `Critical`
|
|
- **Impact:** Developers won't know which naming is canonical.
|
|
- **Fix:** Align on PRD naming (Aggressive → Critical can be added as an alias). The PRD version is more descriptive and covers more use cases (includes `None` and `Custom`).
|
|
|
|
### X-04: PRD Phase 3 Timeline Differs from Roadmap Phase 3
|
|
|
|
- **PRD (line 705-711):** Phase 3 is 3 weeks (Weeks 5-7)
|
|
- **Roadmap (line 341):** Phase 3 is 4 weeks (Weeks 6-9)
|
|
- **PRD summary (line 788):** "iOS + Apple Watch follows in weeks 5-7"
|
|
- **Impact:** Confusing for anyone reading both docs.
|
|
- **Fix:** Align both to the roadmap's 4-week version (Weeks 6-9), which is already more realistic per T-02. Update PRD phases section to match.
|
|
|
|
### X-05: Success Metrics Contradict Between PRD and Roadmap
|
|
|
|
- **PRD Section 12:** MVP targets: 100 PWA installs, 50 DAU, 500+ timers/week
|
|
- **Roadmap Success Playbook:** MVP targets: 50 MAU, >40% DAU/MAU ratio
|
|
- **Impact:** Two different success criteria for the same phase.
|
|
- **Fix:** Reconcile. PRD's are more specific and measurable. Roadmap should adopt PRD's metrics for Phase 1, then layer in the viral/growth metrics for later phases.
|
|
|
|
### X-06: PRD Says "Open-Source" — Roadmap Never Discusses Licensing
|
|
|
|
- **PRD line 664:** "ChronoMind is **free and open-source** for personal use."
|
|
- **Roadmap:** No mention of licensing, open-source, or repository visibility.
|
|
- **Impact:** Open-source has massive implications: competitors can fork, community can contribute, monetization strategy changes.
|
|
- **Fix:** Add to Appendix B decisions: "Open-source vs closed-source." If open-source, define license (MIT? AGPL? Business Source License?). If closed-source, remove from PRD. **Recommendation:** Start closed-source, open-source the timer engine library only (good for credibility + community), keep the app itself proprietary.
|
|
|
|
### X-07: PRD Feature #49 "AI Suggestions" Not in Roadmap
|
|
|
|
- **PRD line 232:** `AI suggestions — "You have a gap between 2-3pm, want to schedule focus time?"`
|
|
- **Roadmap:** Not mentioned in any phase.
|
|
- **Fix:** Add to Phase 4 or 5 as a stretch goal. Requires calendar integration (Phase 4) to detect gaps. Label as "v2 stretch" in both docs.
|
|
|
|
### X-08: Neurodivergent Mode — Toggle vs Default Contradicts
|
|
|
|
- **PRD Open Question #7 (line 747):** "Decision: design for neurodivergent by default (visual timers, gentle transitions); add 'compact mode' for power users"
|
|
- **Roadmap Phase 2 (line 290-299):** Treats neurodivergent mode as a separate toggle in settings ("Gentle mode")
|
|
- **Impact:** These are opposite approaches. Default-on vs opt-in toggle.
|
|
- **Fix:** Follow the PRD decision — neurodivergent-friendly IS the default UX. The toggle should be "Compact mode" (for power users who want dense UI), not "Gentle mode" (which implies the default is harsh). Update roadmap Phase 2 checklist.
|
|
|
|
### X-09: PRD Design System (`--cm-*`) Conflicts with ByteLyst Tokens
|
|
|
|
- **PRD Section 9.1:** Defines a complete ChronoMind-specific color palette with `--cm-*` prefix. Colors are notably different from ByteLyst's:
|
|
- ChronoMind bg: `#0A0B0F`, ByteLyst bg: `#06070A`
|
|
- ChronoMind accent: `#5B8DEE`, ByteLyst accent: `#5A8CFF`
|
|
- ChronoMind has urgency-specific colors: critical `#FF4757`, important `#FF9F43`, standard `#FECA57`, gentle `#2ED573`
|
|
- ByteLyst has no urgency-level colors at all
|
|
- **V2 review D-01** recommended extending `bytelyst.tokens.json` but didn't address this color conflict.
|
|
- **Fix:** ChronoMind needs its **own product section** in the token file (like the `brain` section exists for MindLyst). Add a `chronomind` section with urgency colors, timer-specific tokens, and the `--cm-*` prefix. The base palette (neutral, spacing, typography, motion) can be shared; the semantic/product colors are ChronoMind's own. Update `generate.ts` to produce `chronomind.tokens.css` alongside the existing outputs.
|
|
|
|
### X-10: PRD Typography Differs from ByteLyst Tokens
|
|
|
|
- **PRD line 594-596:** Display: Space Grotesk (shared), Body: **Inter**, Mono: **JetBrains Mono**
|
|
- **ByteLyst tokens line 80-83:** Display: Space Grotesk (shared), Body: **DM Sans**, Mono: **IBM Plex Mono**
|
|
- **Impact:** Different body and mono fonts across ecosystem products.
|
|
- **Fix:** Decision needed: match ByteLyst fonts (DM Sans / IBM Plex Mono) for ecosystem consistency, or keep Inter / JetBrains Mono for ChronoMind's identity? **Recommendation:** Keep ChronoMind's fonts — timer/clock apps need excellent tabular numbers, and JetBrains Mono has superior digit rendering for countdown displays. Add `fontFamily.chronomind` section to tokens.
|
|
|
|
### X-11: PRD Notification Architecture Mentions SW 30s Check — Roadmap Says `requestAnimationFrame`
|
|
|
|
- **PRD Section 8.3 (line 486-507):** Timer engine runs in Service Worker, scheduler checks every 30 seconds, has fallback to `setInterval` in active tab.
|
|
- **Roadmap Phase 1 (line 75):** Timer engine uses `requestAnimationFrame` + `setInterval` dual-loop.
|
|
- **Impact:** These are different architectures. `requestAnimationFrame` runs in the main thread (stops when tab is hidden). SW runs in background.
|
|
- **Fix:** Both are needed. Clarify in roadmap: `requestAnimationFrame` for UI countdown display (smooth 60fps), `setInterval` in SW for background notification scheduling. The timer engine must work in BOTH contexts.
|
|
|
|
### X-12: Extraction Service as NL Upgrade Path — Missed Reuse
|
|
|
|
- **Common-plat:** `@bytelyst/extraction` package + extraction-service (port 4005) provides LLM-powered entity extraction with configurable tasks, examples, and classes.
|
|
- **Roadmap Phase 2:** NL parsing uses `chrono-node` only (local regex-based). PRD Open Question #2 says "optional LLM v2."
|
|
- **Fix:** Add to Phase 4 as an upgrade path: "Advanced NL parsing via extraction-service — define a `timer-parse` extraction task with classes like `time`, `duration`, `urgency_hint`, `label`, `recurrence`. Falls back to chrono-node if extraction-service is unavailable." This reuses existing infrastructure instead of building a new LLM integration.
|
|
|
|
---
|
|
|
|
## 11. Platform Dependencies & Blockers
|
|
|
|
The common-plat `PLATFORM_COMPONENTS_ROADMAP.md` identifies **25 gap components** that don't exist yet. Several of these are **direct blockers** for ChronoMind features:
|
|
|
|
### Blockers for ChronoMind
|
|
|
|
| Gap Component | Priority | ChronoMind Feature Blocked | Status |
|
|
|---------------|----------|---------------------------|--------|
|
|
| **Email/Push Delivery (2.2)** | P0 | Shared timer notifications, waitlist emails, referral invites | Not built |
|
|
| **Password Reset + Email Verification (2.5)** | P0 | User account creation (Phase 4-5) | Not built |
|
|
| **Event Bus (2.4)** | P0 | Shared timer real-time sync, webhook delivery | Not built |
|
|
| **Data Export (2.9)** | P1 | GDPR compliance, "Export all my data" (M-02) | Not built |
|
|
| **Scheduled Jobs (2.1)** | P0 | Calendar sync polling (every 15 min), recurring timer generation | Not built |
|
|
|
|
### Impact
|
|
|
|
- **Phase 1-3 (Web + iOS):** No blockers — everything is local/offline.
|
|
- **Phase 4 (Accounts + Sync):** Blocked by Email Delivery (2.2) and Password Reset (2.5). Cannot create user accounts without email verification.
|
|
- **Phase 5 (Shared timers):** Blocked by Event Bus (2.4) for real-time updates, and Email Delivery (2.2) for household invitations.
|
|
|
|
### Mitigation
|
|
|
|
- **Phase 1-3:** Proceed independently — no backend needed.
|
|
- **Phase 4 preparation:** Coordinate with common-plat sprint plan. Email Delivery + Password Reset are on the critical path (Sprint 1-2 per PLATFORM_COMPONENTS_ROADMAP). If they aren't built by Phase 4, ChronoMind can:
|
|
- Use Apple Sign-In / Google Sign-In only (skip email/password accounts initially)
|
|
- Use CloudKit for Apple-only sync (no platform-service dependency)
|
|
- **Phase 5:** Event Bus is Sprint 1 priority. If delayed, shared timers can use polling (30s interval) as a degraded experience.
|
|
|
|
### AKV Secret Mapping Needed
|
|
|
|
Like `LYSNR_SECRETS` in `@bytelyst/config`, ChronoMind needs `CHRONO_SECRETS`:
|
|
|
|
```typescript
|
|
export const CHRONO_SECRETS = {
|
|
COSMOS_KEY: { envVar: 'COSMOS_KEY', akvName: 'chrono-cosmos-key' },
|
|
JWT_SECRET: { envVar: 'JWT_SECRET', akvName: 'chrono-jwt-secret' },
|
|
STRIPE_SECRET_KEY: { envVar: 'STRIPE_SECRET_KEY', akvName: 'chrono-stripe-secret-key' },
|
|
STRIPE_WEBHOOK_SECRET: { envVar: 'STRIPE_WEBHOOK_SECRET', akvName: 'chrono-stripe-webhook-secret' },
|
|
} as const;
|
|
```
|
|
|
|
**Or:** Share the same Cosmos DB and JWT secret as LysnrAI (since `productId` partitions data). Decision needed in Appendix B.
|
|
|
|
---
|
|
|
|
## 12. 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** |
|
|
| X-09 | Design tokens conflict (`--cm-*` vs ByteLyst) | Add ChronoMind product section to token file, keep urgency colors | **P0** |
|
|
| B-02 | Phase 4/5 cloud sync contradiction | iCloud in Phase 3, REST API in Phase 5 | **P0** |
|
|
| X-03 | Cascade preset names don't match PRD ↔ roadmap | Align on PRD naming (Aggressive/Standard/Light/Minimal/None) | **P0** |
|
|
| X-06 | Open-source vs closed-source undecided | Start closed-source, open-source timer engine lib only | **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** |
|
|
| X-04 | PRD and roadmap Phase 3 timelines differ | Align both to 4 weeks (Weeks 6-9) | **P1** |
|
|
| X-05 | Success metrics contradict PRD ↔ roadmap | Adopt PRD's specific metrics (100 PWA installs, 50 DAU) | **P1** |
|
|
| X-08 | Neurodivergent mode toggle vs default | Follow PRD: neurodivergent-friendly IS default, add "Compact mode" | **P1** |
|
|
| X-11 | Timer engine architecture unclear (SW vs rAF) | Both needed: rAF for UI, setInterval in SW for background | **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** |
|
|
| X-01 | Windows/Tauri in PRD but not roadmap | Either add Phase 6 or move to v3 in PRD | **P2** |
|
|
| X-02 | Event countdown timer type never scheduled | Add to Phase 2 Week 4 | **P2** |
|
|
| X-10 | Typography differs (Inter vs DM Sans) | Keep ChronoMind fonts (better for digits) | **P2** |
|
|
| X-12 | Extraction service unused for NL | Add as Phase 4 upgrade path from chrono-node | **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** |
|
|
| X-07 | AI suggestions not in roadmap | Add to Phase 4-5 as stretch | **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 |
|
|
| 11 | **Open-source strategy** | Full open-source vs closed-source vs hybrid | Hybrid: open-source timer engine lib, proprietary app | Affects community, competitors, monetization |
|
|
| 12 | **Windows/Tauri** | Phase 5 vs Phase 6 vs v3 | Defer to v3 | Not enough market signal yet, focus on mobile |
|
|
| 13 | **Shared AKV secrets** | Own CHRONO_SECRETS vs share with LysnrAI | Share Cosmos/JWT (productId partitions), own Stripe keys | Fewer secrets to manage, same infra |
|
|
| 14 | **Fonts** | Match ByteLyst (DM Sans, IBM Plex Mono) vs own (Inter, JetBrains Mono) | Own fonts — JetBrains Mono has superior digit rendering | Timer app needs excellent tabular numbers |
|