a9dc99ec23
- Add INDUSTRY_RESEARCH.md: market sizing, 9 competitors, 24 feature demands, trends - Update PRD to v0.2: Next.js 16 + React 19 + TailwindCSS v4 stack - Add visual timeline, Pomodoro, neurodivergent mode, AI reschedule features - Promote iOS + Apple Watch to v1.0, add new v1.1 context phase - Expand competitive analysis (Tiimo, Structured, Alarmy, TickTick, Forest, etc.) - Add risk assessment section, revised monetization (Family tier) - Update development phases to realistic 11-week roadmap
788 lines
41 KiB
Markdown
788 lines
41 KiB
Markdown
# ChronoMind — AI-Powered Contextual Clock & Timer
|
||
|
||
> **Product:** ChronoMind
|
||
> **Repo:** `learning_ai_clock`
|
||
> **Version:** 0.2 (MVP — revised after industry research)
|
||
> **Date:** February 2026
|
||
> **Author:** Saravana
|
||
> **Research:** See [INDUSTRY_RESEARCH.md](INDUSTRY_RESEARCH.md) for full competitive analysis
|
||
|
||
---
|
||
|
||
## 1. Origin (Raw Idea)
|
||
|
||
> Build an alarm clock to set a specified date and time and also give a warning maybe with a configured 1 hour to 2 hours before that. For example if the alarm is going to go off in 2 hours, so that the user can remember or take action or let it ring depending on the critical task they are supposed to do during the time.
|
||
|
||
---
|
||
|
||
## 2. Vision
|
||
|
||
**ChronoMind** is a context-aware, AI-augmented **time awareness layer** that understands *why* you set a timer — not just *when*. It provides intelligent pre-warnings, adaptive escalation, routine orchestration, and natural language interaction. It bridges the gap between dumb alarms and full calendar apps by focusing on one thing: **making sure you never miss what matters, and always have time to prepare.**
|
||
|
||
### Market Context (2026)
|
||
|
||
The productivity app market is valued at **$13.15B (2025)** growing to **$30.85B by 2034** at 9.94% CAGR. Tiimo (visual planner) won **Apple's iPhone App of the Year 2025**, validating that visual, AI-powered time management is mainstream. Structured has millions of users with its timeline-first approach. Yet **no existing app combines pre-warning cascades + urgency intelligence + routine orchestration + visual timelines in a single product.**
|
||
|
||
ChronoMind is not a clock app. Not a calendar app. Not a Pomodoro app. It's a **time awareness layer** that sits alongside your calendar and makes sure you're never caught off-guard.
|
||
|
||
### The Problem with Current Timers & Clocks
|
||
|
||
| Gap | Current Market | ChronoMind |
|
||
|-----|---------------|------------|
|
||
| **No pre-warnings** | Alarm fires once, at the exact time | Configurable cascade: 2h → 1h → 30m → 15m → 5m → NOW |
|
||
| **No context** | "Alarm at 3:00 PM" — why? | "Meeting with Sarah in 2 hours — prep slides?" |
|
||
| **No urgency levels** | Every alarm sounds the same | Critical (can't miss) → Important → Casual → Gentle |
|
||
| **No prep-time awareness** | You set alarm for meeting at 3pm, forget 20min prep | Auto-adds prep buffer: "Start preparing at 2:40 PM" |
|
||
| **No travel awareness** | Alarm for dentist at 2pm, 30min drive away | "Leave by 1:25 PM (traffic is heavy today)" |
|
||
| **No chaining** | Timer for pasta, but forget sauce timing | Linked timers: "Boil water → Add pasta → Start sauce at T-3min" |
|
||
| **No routines** | Set same 5 alarms every morning manually | "Morning routine" = Wake → Meditate (10m) → Exercise (30m) → Shower (15m) → Leave |
|
||
| **No countdown to events** | Separate app for "days until vacation" | Built-in event countdown with milestone warnings |
|
||
| **No shared timers** | Can't coordinate with family/team | "Pizza timer" visible to everyone in household |
|
||
| **No natural language** | Tap through 4 screens to set a timer | "Remind me to call Mom 2 hours before my flight" |
|
||
| **No adaptive snooze** | Fixed 5/10min snooze | Snooze learns: "You always snooze this one 3 times — should I set it 15min earlier?" |
|
||
| **No focus integration** | Timer has no concept of deep work | "Block notifications for 90min, warn me 10min before standup" |
|
||
| **No voice** | Visual-only or basic "Hey Siri" | Full voice control: "What's my next timer?" / "Push everything back 30 minutes" |
|
||
| **No visual timeline** | Flat list of alarms | Structured vertical timeline showing your entire day at a glance |
|
||
| **No AI replanning** | Missed alarm = chaos | "I slept in 30 min — reschedule my morning" |
|
||
| **No neurodivergent support** | One-size-fits-all | Visual timers, gentle transitions, ADHD time-blindness support |
|
||
|
||
---
|
||
|
||
## 3. Target Platforms
|
||
|
||
| Phase | Platform | Tech Stack |
|
||
|-------|----------|------------|
|
||
| **MVP** | Web app (PWA) | Next.js 16 (App Router), React 19, TailwindCSS v4 + shadcn/ui |
|
||
| **v1.0** | iOS app + Apple Watch | SwiftUI (native), WidgetKit, Live Activities |
|
||
| **v1.1** | macOS menu bar | SwiftUI (native, shared code with iOS) |
|
||
| **v2.0** | Android + Wear OS | Jetpack Compose, Glance widgets |
|
||
| **v2.0** | Windows | Tauri |
|
||
|
||
> **MVP is web-first** — works on any device, installable as PWA with notification support.
|
||
> **v1.0 fast-follows with iOS** — timer apps live on the wrist; Apple Watch is table stakes in 2026.
|
||
>
|
||
> **PWA notification note:** iOS PWA push notifications are supported since iOS 16.4 but require home screen installation and are less reliable than native push. Tab title countdown is used as a supplementary signal. Native iOS app is prioritized for v1.0 to ensure alarm reliability.
|
||
|
||
---
|
||
|
||
## 4. Core Concepts
|
||
|
||
### 4.1 Timer Types
|
||
|
||
| Type | Description | Example |
|
||
|------|-------------|---------|
|
||
| **Alarm** | Fires at a specific date/time | "Wake up at 6:30 AM" |
|
||
| **Countdown** | Fires after a duration | "Timer for 25 minutes" |
|
||
| **Pomodoro** | Focus session with work/break intervals | "4 rounds × 25min work / 5min break" |
|
||
| **Event Countdown** | Days/hours until a future date | "14 days until vacation" |
|
||
| **Routine** | Ordered sequence of timed steps | "Morning routine (5 steps, 75 min total)" |
|
||
| **Linked Timer** | Timer that triggers another timer | "When pasta timer ends, start sauce timer" |
|
||
| **Recurring** | Repeats on a schedule | "Every weekday at 9:00 AM" |
|
||
| **Shared** | Visible/controllable by multiple people | "Family dinner timer" (v2) |
|
||
|
||
### 4.2 Urgency Levels
|
||
|
||
Every timer has an urgency level that controls notification behavior:
|
||
|
||
```
|
||
┌─────────────┬────────────────────────────────────────────────────────────────┐
|
||
│ Level │ Behavior │
|
||
├─────────────┼────────────────────────────────────────────────────────────────┤
|
||
│ CRITICAL │ Full screen takeover, persistent sound, vibration, cannot │
|
||
│ │ dismiss without acknowledgment. Pre-warnings at 2h, 1h, 30m, │
|
||
│ │ 15m, 5m, 1m. Example: flight departure, job interview. │
|
||
│ │ │
|
||
│ IMPORTANT │ Prominent notification with sound. Pre-warnings at 1h, 30m, │
|
||
│ │ 15m, 5m. Snooze allowed (max 3x). Example: team meeting, │
|
||
│ │ doctor appointment. │
|
||
│ │ │
|
||
│ STANDARD │ Normal notification with gentle sound. Pre-warnings at 30m, │
|
||
│ │ 5m. Snooze allowed. Example: laundry, cooking timer. │
|
||
│ │ │
|
||
│ GENTLE │ Silent notification (badge/banner only). Single pre-warning │
|
||
│ │ at 15m. Auto-dismiss after 2 minutes. Example: "check on │
|
||
│ │ bread in oven", casual reminder. │
|
||
│ │ │
|
||
│ PASSIVE │ No notification at all — just visible in the app timeline. │
|
||
│ │ For event countdowns and tracking. Example: "days until │
|
||
│ │ vacation", "months until lease renewal". │
|
||
└─────────────┴────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.3 Pre-Warning Cascade
|
||
|
||
The core differentiator. Every timer can have a **configurable cascade** of pre-warnings before the main alarm fires.
|
||
|
||
```
|
||
Example: Flight at 2:00 PM (CRITICAL)
|
||
|
||
10:00 AM [-4h] "Flight to NYC in 4 hours. Have you packed?"
|
||
11:00 AM [-3h] "Flight in 3 hours. Check-in reminder."
|
||
12:00 PM [-2h] "Flight in 2 hours. Start getting ready."
|
||
12:30 PM [-90m] "Flight in 90 minutes. Suggested: leave in 45 min."
|
||
1:00 PM [-1h] "Flight in 1 HOUR. Leave NOW if driving."
|
||
1:30 PM [-30m] "Flight in 30 minutes. You should be at airport."
|
||
1:45 PM [-15m] "BOARDING SOON — 15 minutes."
|
||
2:00 PM [ 0 ] "FLIGHT TIME — NOW"
|
||
```
|
||
|
||
**Default cascade presets:**
|
||
|
||
| Preset | Warnings At | Best For |
|
||
|--------|-------------|----------|
|
||
| **Aggressive** | 4h, 3h, 2h, 90m, 1h, 30m, 15m, 5m, 1m | Flights, once-in-a-lifetime events |
|
||
| **Standard** | 2h, 1h, 30m, 15m, 5m | Meetings, appointments |
|
||
| **Light** | 1h, 15m, 5m | Cooking, laundry, casual |
|
||
| **Minimal** | 15m | Gentle reminders |
|
||
| **None** | — (fire only) | Simple countdown timers |
|
||
| **Custom** | User-defined | Any |
|
||
|
||
### 4.4 Prep Time & Travel Time
|
||
|
||
Timers can optionally include **prep time** and **travel time** that shifts warnings earlier.
|
||
|
||
```
|
||
Example: Dentist at 2:00 PM
|
||
+ Prep time: 15 min (get dressed, grab wallet)
|
||
+ Travel time: 25 min (auto-estimated or manual)
|
||
+ Buffer: 5 min (arrive early)
|
||
|
||
Effective "start preparing" time: 1:15 PM
|
||
Effective "leave by" time: 1:30 PM
|
||
|
||
Warnings shift to target 1:15 PM for prep, 1:30 PM for departure.
|
||
```
|
||
|
||
**Travel time estimation** (v1.1+):
|
||
- Manual entry (MVP)
|
||
- Integration with maps API for real-time traffic estimates (v2)
|
||
- Learn from past patterns: "You usually take 35 min to get to the office"
|
||
|
||
---
|
||
|
||
## 5. Feature Breakdown
|
||
|
||
### 5.1 MVP (v0.1) — Web PWA
|
||
|
||
| # | Feature | Priority | Description |
|
||
|---|---------|----------|-------------|
|
||
| 1 | **Create alarm** | P0 | Set date/time, label, urgency level |
|
||
| 2 | **Create countdown** | P0 | Set duration, label, urgency level |
|
||
| 3 | **Pre-warning cascade** | P0 | Configure cascade per timer (presets + custom) |
|
||
| 4 | **Urgency levels** | P0 | 5 levels controlling notification style |
|
||
| 5 | **Visual timeline dashboard** | P0 | Vertical timeline (à la Structured/Tiimo) showing your day at a glance |
|
||
| 6 | **Browser notifications** | P0 | Push notifications via Web Notifications API + Service Worker |
|
||
| 7 | **Sound alerts** | P0 | Multiple alarm sounds, volume per urgency, haptic patterns |
|
||
| 8 | **Snooze / dismiss** | P0 | Snooze with configurable duration, dismiss with confirmation for CRITICAL |
|
||
| 9 | **Quick timer** | P0 | One-tap presets: 5m, 15m, 25m (pomodoro), 1h |
|
||
| 10 | **Pomodoro timer** | P0 | First-class focus sessions with work/break intervals and round tracking |
|
||
| 11 | **Timer labels + notes** | P1 | Add context: "Call Dr. Smith — phone: 555-1234" |
|
||
| 12 | **Dark + light theme** | P1 | Both themes with system preference detection (dark default) |
|
||
| 13 | **PWA install** | P1 | Installable on mobile/desktop via browser |
|
||
| 14 | **Local storage** | P1 | All data in IndexedDB — no account needed, offline-first |
|
||
| 15 | **Recurring timers** | P1 | Daily, weekday, weekly, monthly, custom cron |
|
||
| 16 | **Tab title countdown** | P1 | Show "⏱ 14:32 — Standup" in browser tab (compensates for PWA notification gaps) |
|
||
| 17 | **Keyboard shortcuts** | P2 | Quick-create, navigate, snooze |
|
||
| 18 | **Timer history** | P2 | Past timers log with stats |
|
||
| 19 | **Contextual pre-warning messages** | P1 | AI-generated messages like "Have you packed?" based on timer label/context |
|
||
|
||
### 5.2 v1.0 — Intelligence + iOS
|
||
|
||
| # | Feature | Description |
|
||
|---|---------|-------------|
|
||
| 20 | **Natural language input** | "Remind me to call Mom at 3pm with 1 hour warning" (local regex MVP, LLM for complex) |
|
||
| 21 | **Routines** | Create ordered sequences of timed steps |
|
||
| 22 | **Linked timers** | "When timer A ends, start timer B" |
|
||
| 23 | **Prep time** | Add preparation buffer before any timer |
|
||
| 24 | **Calendar import (.ics)** | Import from .ics files or calendar URL (read-only) — reduces double-entry friction |
|
||
| 25 | **Focus mode** | Block notifications, only allow CRITICAL through; integrates with OS DND |
|
||
| 26 | **Event countdowns** | "132 days until wedding" with milestone warnings |
|
||
| 27 | **Categories / tags** | Work, Personal, Health, Cooking, etc. |
|
||
| 28 | **Statistics + streaks** | Timers set, snooze rate, on-time rate, focus streaks, gamification elements |
|
||
| 29 | **Adaptive snooze** | Learn snooze patterns, suggest earlier alarm |
|
||
| 30 | **AI reschedule** | "I slept in 30 min — shift my morning" (Structured 4.0's killer feature) |
|
||
| 31 | **iOS native app** | SwiftUI, full notification support, reliable background alarms |
|
||
| 32 | **Apple Watch** | Complications, Live Activities on Dynamic Island, haptic pre-warnings |
|
||
| 33 | **iOS widgets** | Home screen + Lock Screen widgets showing next timer and countdown |
|
||
| 34 | **Neurodivergent mode** | Visual countdown rings, gentle transitions, time-blindness aids, reduced cognitive load |
|
||
|
||
### 5.3 v1.1 — Context & Sync
|
||
|
||
| # | Feature | Description |
|
||
|---|---------|-------------|
|
||
| 35 | **Calendar sync (full)** | Two-way sync with Google Calendar, Apple Calendar, Outlook |
|
||
| 36 | **Location-based triggers** | "Remind me when I leave home" — geofence-aware timers |
|
||
| 37 | **Travel time (live)** | Maps API integration for real-time traffic estimates |
|
||
| 38 | **Sleep integration** | Bedtime routine, wake-up intelligence, sleep quality tracking |
|
||
| 39 | **Mood/energy check-in** | Quick post-timer mood check; contextualizes productivity patterns |
|
||
| 40 | **Cloud sync (optional)** | End-to-end encrypted cross-device sync, privacy-first |
|
||
| 41 | **macOS menu bar** | SwiftUI, shared code with iOS app |
|
||
|
||
### 5.4 v2.0 — Platform Expansion & Social
|
||
|
||
| # | Feature | Description |
|
||
|---|---------|-------------|
|
||
| 42 | **Shared timers** | Family/household timers visible to invited users |
|
||
| 43 | **Voice control** | "What's my next alarm?" / "Push everything back 30 minutes" |
|
||
| 44 | **Android + Wear OS** | Jetpack Compose, Glance widgets |
|
||
| 45 | **Windows** | Tauri desktop app |
|
||
| 46 | **API** | REST API for programmatic timer management |
|
||
| 47 | **Webhooks / Zapier** | Timer events trigger external actions |
|
||
| 48 | **Smart Home** | HomeKit/Alexa triggers: "Dim lights when wind-down routine starts" |
|
||
| 49 | **AI suggestions** | "You have a gap between 2-3pm, want to schedule focus time?" |
|
||
| 50 | **Body doubling** | Shared focus sessions with accountability partners |
|
||
|
||
---
|
||
|
||
## 6. Routines (Deep Dive)
|
||
|
||
Routines are a killer feature that no current timer app does well. A routine is an **ordered sequence of timed activities** with transitions.
|
||
|
||
### Example: Morning Routine
|
||
|
||
```
|
||
Morning Routine Total: 1h 35m
|
||
|
||
Step 1: Wake Up + Hydrate 5 min 6:00 - 6:05
|
||
Step 2: Meditation 15 min 6:05 - 6:20
|
||
Step 3: Exercise 30 min 6:20 - 6:50
|
||
Step 4: Shower + Get Ready 20 min 6:50 - 7:10
|
||
Step 5: Breakfast 15 min 7:10 - 7:25
|
||
Step 6: Commute Buffer 10 min 7:25 - 7:35
|
||
|
||
Notification at each step transition
|
||
"Skip step" and "Extend +5min" buttons on each notification
|
||
Tracks actual vs planned duration over time
|
||
```
|
||
|
||
### Example: Cooking Routine (Linked Timers)
|
||
|
||
```
|
||
Thanksgiving Dinner Prep (work backwards from 6:00 PM serve time)
|
||
|
||
2:00 PM Turkey in oven (4 hours)
|
||
4:30 PM Start mashed potatoes (45 min)
|
||
5:00 PM Start gravy (30 min)
|
||
5:15 PM Rolls in oven (25 min)
|
||
5:30 PM Set table (15 min)
|
||
5:45 PM Turkey resting (15 min, auto-started when turkey timer ends)
|
||
6:00 PM Serve!
|
||
|
||
All timers visible in one timeline view with progress bars.
|
||
```
|
||
|
||
### Example: Pomodoro Focus Session
|
||
|
||
```
|
||
Focus Session: "Write PRD"
|
||
|
||
Round 1: 25 min work -> 5 min break
|
||
Round 2: 25 min work -> 5 min break
|
||
Round 3: 25 min work -> 5 min break
|
||
Round 4: 25 min work -> 15 min long break
|
||
|
||
Total: 2h 10m
|
||
Focus mode active (only CRITICAL timers break through)
|
||
Track completed rounds, interruptions
|
||
```
|
||
|
||
---
|
||
|
||
## 7. User Interface
|
||
|
||
### 7.1 Design Principles
|
||
|
||
| Principle | Rationale |
|
||
|-----------|-----------|
|
||
| **Glanceable** | See time-to-next-alarm in < 1 second |
|
||
| **One-tap creation** | Quick timer presets always visible |
|
||
| **Dark-first** | Alarm apps are used in bed, at night |
|
||
| **Information density** | Power users want to see all timers at once |
|
||
| **Accessible** | Large touch targets, high contrast, screen reader support |
|
||
| **Beautiful sounds** | Alarm sounds that don't trigger anxiety |
|
||
|
||
### 7.2 Key Screens
|
||
|
||
```
|
||
SCREEN MAP
|
||
|
||
Dashboard Create Routines
|
||
(Home) Timer
|
||
|
||
- Clock - Alarm - Templates
|
||
- Next up - Countdown - Active
|
||
- Timeline - Event - History
|
||
- Quick - Routine
|
||
presets - NL input
|
||
|
||
Focus History Settings
|
||
Mode & Stats
|
||
|
||
- Pomodoro - Past - Sounds
|
||
- Custom timers - Defaults
|
||
- DND sync - Streaks - Theme
|
||
- Insights - Backup
|
||
- Import
|
||
```
|
||
|
||
### 7.3 Dashboard Layout
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ ChronoMind Settings │
|
||
├──────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 10:42:38 AM │
|
||
│ Thursday, Feb 27 │
|
||
│ │
|
||
│ -- NEXT UP --------------------------------------------------------│
|
||
│ | [IMPORTANT] Team Standup in 1h 18m │
|
||
│ | Pre-warning in 18 min - Prep: review tickets (15 min) │
|
||
│ ------------------------------------------------------------------ │
|
||
│ │
|
||
│ -- QUICK TIMER --------------------------------------------------- │
|
||
│ | [ 5m ] [ 15m ] [ 25m ] [ 1h ] [ Custom ] [ NL Input ] │
|
||
│ ------------------------------------------------------------------ │
|
||
│ │
|
||
│ -- TIMELINE ------------------------------------------------------ │
|
||
│ | | │
|
||
│ | 12:00 PM [IMPORTANT] Team Standup ............. in 1h 18m | │
|
||
│ | Pre-warning at 11:00 AM (in 18m) | │
|
||
│ | | │
|
||
│ | 2:00 PM [STANDARD] Dentist Appointment ....... in 3h 18m | │
|
||
│ | Leave by 1:30 PM (25 min drive) | │
|
||
│ | | │
|
||
│ | 5:00 PM [GENTLE] Pick up dry cleaning ........ in 6h 18m | │
|
||
│ | | │
|
||
│ | 6:30 PM [STANDARD] Pasta timer (linked) ...... in 7h 48m | │
|
||
│ | -> Sauce timer starts when this ends | │
|
||
│ | | │
|
||
│ | -- Tomorrow -------------------------------------------------- | │
|
||
│ | 6:00 AM Morning Routine (1h 35m) ............ in 19h 18m | │
|
||
│ | 9:00 AM [IMPORTANT] Sprint Planning ......... in 22h 18m | │
|
||
│ | | │
|
||
│ | -- Event Countdowns ------------------------------------------ | │
|
||
│ | [PASSIVE] Vacation in 47 days | │
|
||
│ | [PASSIVE] Lease renewal in 132 days | │
|
||
│ | | │
|
||
│ ------------------------------------------------------------------ │
|
||
│ │
|
||
│ -- ACTIVE ROUTINES ---------------------------------------------- │
|
||
│ | Morning Routine Weekdays at 6:00 AM [Edit] | │
|
||
│ | Pomodoro Focus On-demand [Start] | │
|
||
│ | Wind Down Daily at 9:30 PM [Edit] | │
|
||
│ ------------------------------------------------------------------ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Technical Architecture (MVP)
|
||
|
||
### 8.1 Stack
|
||
|
||
| Layer | Technology | Rationale |
|
||
|-------|-----------|-----------|
|
||
| **Framework** | Next.js 16 (App Router) | Current stable, App Router is the standard, excellent PWA support with Server Components |
|
||
| **UI** | React 19 + TailwindCSS v4 + shadcn/ui | Modern, accessible, themeable components; Lucide React for icons |
|
||
| **State** | Zustand | Lightweight, persists to IndexedDB |
|
||
| **Storage** | IndexedDB (via idb) | Offline-first, no backend needed for MVP |
|
||
| **Notifications** | Web Notifications API + Service Worker | Works when app is backgrounded (PWA) |
|
||
| **Audio** | Web Audio API | Low-latency alarm sounds |
|
||
| **Time** | date-fns | Lightweight date manipulation |
|
||
| **PWA** | @serwist/next (Serwist) | Active successor to next-pwa (unmaintained); service worker, offline, installable |
|
||
| **NL Parsing** | chrono-node (local) | Natural language date/time parsing without LLM dependency |
|
||
| **Testing** | Vitest + Playwright | Unit + E2E |
|
||
| **Analytics** | Plausible (self-hosted) or PostHog | Privacy-first analytics for PWA install, feature adoption tracking |
|
||
|
||
### 8.2 Data Model
|
||
|
||
```typescript
|
||
interface Timer {
|
||
id: string; // UUID
|
||
type: 'alarm' | 'countdown' | 'pomodoro' | 'event' | 'routine_step';
|
||
label: string;
|
||
notes?: string;
|
||
urgency: 'critical' | 'important' | 'standard' | 'gentle' | 'passive';
|
||
|
||
// When it fires
|
||
targetTime: Date; // For alarms: specific datetime
|
||
duration?: number; // For countdowns: milliseconds
|
||
startedAt?: Date; // For countdowns: when started
|
||
|
||
// Pre-warning cascade
|
||
cascade: CascadePreset | number[]; // Preset name or custom minutes array
|
||
preWarnings: PreWarning[]; // Computed from cascade
|
||
|
||
// Optional enhancements
|
||
prepTime?: number; // Minutes of preparation time
|
||
travelTime?: number; // Minutes of travel time
|
||
location?: string; // For travel time estimation
|
||
|
||
// Recurrence
|
||
recurrence?: RecurrenceRule;
|
||
|
||
// Linking
|
||
linkedTimerId?: string; // Timer to start when this one fires
|
||
routineId?: string; // Parent routine
|
||
routineStep?: number; // Step index in routine
|
||
|
||
// State
|
||
status: 'active' | 'paused' | 'fired' | 'dismissed' | 'snoozed';
|
||
snoozedUntil?: Date;
|
||
snoozeCount: number;
|
||
firedAt?: Date;
|
||
dismissedAt?: Date;
|
||
acknowledgedAt?: Date; // For CRITICAL: must explicitly acknowledge
|
||
|
||
// Metadata
|
||
category?: string;
|
||
tags: string[];
|
||
createdAt: Date;
|
||
updatedAt: Date;
|
||
}
|
||
|
||
interface PreWarning {
|
||
minutesBefore: number;
|
||
message: string;
|
||
firedAt?: Date;
|
||
status: 'pending' | 'fired' | 'skipped';
|
||
}
|
||
|
||
interface Routine {
|
||
id: string;
|
||
name: string;
|
||
steps: RoutineStep[];
|
||
totalDuration: number; // Computed sum
|
||
schedule?: RecurrenceRule; // When this routine runs
|
||
status: 'template' | 'active' | 'completed';
|
||
startedAt?: Date;
|
||
currentStep: number;
|
||
}
|
||
|
||
interface RoutineStep {
|
||
label: string;
|
||
duration: number; // Minutes
|
||
notes?: string;
|
||
sound?: string; // Transition sound
|
||
skippable: boolean;
|
||
extendable: boolean; // Allow +5min
|
||
}
|
||
|
||
type CascadePreset = 'aggressive' | 'standard' | 'light' | 'minimal' | 'none';
|
||
|
||
interface RecurrenceRule {
|
||
frequency: 'daily' | 'weekdays' | 'weekends' | 'weekly' | 'monthly' | 'custom';
|
||
daysOfWeek?: number[]; // 0=Sun, 6=Sat
|
||
interval?: number; // Every N days/weeks/months
|
||
endDate?: Date;
|
||
}
|
||
```
|
||
|
||
### 8.3 Notification Architecture
|
||
|
||
```
|
||
Timer Engine (runs in Service Worker)
|
||
|
||
Timer Store --> Scheduler --> Notification
|
||
(IndexedDB) (checks every Dispatcher
|
||
30 seconds)
|
||
|
|
||
┌───────────────────┤
|
||
| |
|
||
Web Push In-App Alert
|
||
(backgrounded) (foregrounded)
|
||
|
||
- OS banner - Full-screen (CRITICAL)
|
||
- Sound - Toast (others)
|
||
- Badge - Sound
|
||
- Vibration
|
||
```
|
||
|
||
**Key challenge:** Browser Service Workers can be killed by the OS. Mitigation:
|
||
- Schedule next-fire via `setTimeout` with periodic checks every 30s
|
||
- Use `navigator.serviceWorker` for background notifications
|
||
- Fallback: `setInterval` poll in active tab
|
||
- Critical timers register OS-level alarms where supported (native app)
|
||
|
||
### 8.4 Project Structure
|
||
|
||
```
|
||
learning_ai_clock/
|
||
├── docs/
|
||
│ ├── raw_idea.md # Original idea
|
||
│ ├── PRD.md # This document
|
||
│ └── INDUSTRY_RESEARCH.md # Market research & competitive analysis
|
||
├── web/ # Next.js 16 web app (App Router)
|
||
│ ├── src/
|
||
│ │ ├── app/ # App Router
|
||
│ │ │ ├── layout.tsx # Root layout (theme, providers)
|
||
│ │ │ ├── page.tsx # Landing page
|
||
│ │ │ ├── (app)/ # App routes (authenticated/main)
|
||
│ │ │ │ ├── layout.tsx # App shell layout (sidebar, header)
|
||
│ │ │ │ ├── page.tsx # Dashboard (timeline + clock)
|
||
│ │ │ │ ├── create/ # Create timer flow
|
||
│ │ │ │ ├── routines/ # Routines management
|
||
│ │ │ │ ├── focus/ # Pomodoro / focus mode
|
||
│ │ │ │ ├── history/ # Timer history & stats
|
||
│ │ │ │ └── settings/ # Settings & preferences
|
||
│ │ │ └── manifest.ts # PWA manifest (dynamic)
|
||
│ │ ├── components/
|
||
│ │ │ ├── ui/ # shadcn/ui components
|
||
│ │ │ ├── Clock.tsx # Large digital clock with glow
|
||
│ │ │ ├── TimerCard.tsx # Individual timer display
|
||
│ │ │ ├── Timeline.tsx # Vertical visual timeline (core UX)
|
||
│ │ │ ├── QuickTimer.tsx # One-tap preset buttons
|
||
│ │ │ ├── CascadeEditor.tsx# Pre-warning cascade config
|
||
│ │ │ ├── PomodoroView.tsx # Pomodoro focus session UI
|
||
│ │ │ ├── RoutineEditor.tsx# Routine step editor
|
||
│ │ │ ├── AlarmOverlay.tsx # Full-screen alarm (CRITICAL)
|
||
│ │ │ ├── NLInput.tsx # Natural language input bar
|
||
│ │ │ └── CountdownRing.tsx# Visual countdown ring (neurodivergent-friendly)
|
||
│ │ ├── lib/
|
||
│ │ │ ├── timer-engine.ts # Core scheduling logic
|
||
│ │ │ ├── store.ts # Zustand store + IndexedDB persistence
|
||
│ │ │ ├── notifications.ts # Web Notifications + Service Worker wrapper
|
||
│ │ │ ├── sounds.ts # Web Audio API sounds
|
||
│ │ │ ├── cascade.ts # Pre-warning cascade logic
|
||
│ │ │ ├── recurrence.ts # Recurrence rule engine
|
||
│ │ │ ├── nl-parser.ts # Natural language time parser (chrono-node)
|
||
│ │ │ └── tab-title.ts # Browser tab title countdown updater
|
||
│ │ └── styles/
|
||
│ │ └── globals.css # Tailwind base + custom properties
|
||
│ ├── public/
|
||
│ │ ├── sounds/ # Alarm sound files (.mp3/.ogg)
|
||
│ │ ├── icons/ # PWA icons (multiple sizes)
|
||
│ │ └── sw.js # Service worker (Serwist-generated)
|
||
│ ├── package.json
|
||
│ ├── next.config.ts
|
||
│ ├── tailwind.config.ts
|
||
│ ├── components.json # shadcn/ui config
|
||
│ └── tsconfig.json
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Design System
|
||
|
||
### 9.1 Color Palette (Dark Theme)
|
||
|
||
| Token | Hex | Use |
|
||
|-------|-----|-----|
|
||
| `--cm-bg` | `#0A0B0F` | Page background |
|
||
| `--cm-surface` | `#12141D` | Cards, panels |
|
||
| `--cm-surface-hover` | `#1A1D2A` | Hover states |
|
||
| `--cm-border` | `#2A2D3A` | Borders |
|
||
| `--cm-text` | `#E8ECF4` | Primary text |
|
||
| `--cm-text-secondary` | `#8A92A6` | Secondary text |
|
||
| `--cm-text-muted` | `#5A6178` | Timestamps, hints |
|
||
| `--cm-critical` | `#FF4757` | Critical urgency |
|
||
| `--cm-important` | `#FF9F43` | Important urgency |
|
||
| `--cm-standard` | `#FECA57` | Standard urgency |
|
||
| `--cm-gentle` | `#2ED573` | Gentle urgency |
|
||
| `--cm-passive` | `#5B8DEE` | Passive/info |
|
||
| `--cm-accent` | `#5B8DEE` | Primary accent, links |
|
||
| `--cm-accent-glow` | `#5B8DEE33` | Glow effects on timers |
|
||
|
||
### 9.2 Typography
|
||
|
||
| Token | Font | Weight | Use |
|
||
|-------|------|--------|-----|
|
||
| `--cm-font-display` | Space Grotesk | 700 | Clock face, timer digits |
|
||
| `--cm-font-body` | Inter | 400/500/600 | Body text, labels |
|
||
| `--cm-font-mono` | JetBrains Mono | 400 | Countdown digits, time displays |
|
||
|
||
### 9.3 Clock Face Digits
|
||
|
||
The main clock display uses a large, beautiful monospaced font with a subtle glow effect:
|
||
|
||
```css
|
||
.clock-display {
|
||
font-family: var(--cm-font-mono);
|
||
font-size: 4rem;
|
||
font-variant-numeric: tabular-nums;
|
||
letter-spacing: 0.05em;
|
||
color: var(--cm-text);
|
||
text-shadow: 0 0 30px var(--cm-accent-glow);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Competitive Analysis
|
||
|
||
### 10.1 Feature Matrix
|
||
|
||
| Feature | iOS Clock | Alarmy | Tiimo | Structured | TickTick | Routinery | Forest | Due | **ChronoMind** |
|
||
|---------|----------|--------|-------|-----------|---------|----------|--------|-----|----------------|
|
||
| Basic alarm | Yes | Yes | No | No | Yes | No | No | Yes | **Yes** |
|
||
| Countdown timer | Yes | No | No | Yes | Yes | Yes | Yes | Yes | **Yes** |
|
||
| Pre-warnings | No | No | No | No | No | No | No | Nag | **Yes (core)** |
|
||
| Urgency levels | No | Partial | No | No | Partial | No | No | No | **Yes** |
|
||
| Cascade config | No | No | No | No | No | No | No | No | **Yes** |
|
||
| Visual timeline | No | No | **Yes** | **Yes** | No | No | No | No | **Yes** |
|
||
| Routines | No | Yes | Yes | No | No | **Yes** | No | No | **Yes** |
|
||
| Linked timers | No | No | No | No | No | No | No | No | **Yes** |
|
||
| Pomodoro | No | No | No | Yes | Yes | No | Yes | No | **Yes** |
|
||
| Prep/travel time | No | No | No | No | No | No | No | No | **Yes** |
|
||
| AI input/replan | Siri | No | **Yes** | **Yes** | Partial | No | No | No | **Yes** |
|
||
| Calendar sync | N/A | No | Yes | Yes | Yes | No | No | No | **Yes (v1)** |
|
||
| Apple Watch | N/A | No | Yes | Yes | Yes | No | No | No | **Yes (v1)** |
|
||
| Widgets | N/A | No | Yes | Yes | Yes | No | No | No | **Yes (v1)** |
|
||
| Gamification | No | Missions | No | No | No | No | **Yes** | No | **Yes (v1)** |
|
||
| Neurodivergent | No | No | **Yes** | Partial | No | Partial | No | No | **Yes** |
|
||
| Shared timers | No | No | No | No | Yes (team) | No | No | No | **Yes (v2)** |
|
||
| Web PWA | No | No | No | No | Web app | No | No | No | **Yes** |
|
||
| Offline-first | N/A | Yes | Yes | Yes | No | Yes | Yes | Yes | **Yes** |
|
||
| Free tier | Yes | Freemium | Freemium | Freemium | Freemium | Freemium | $3.99 | $7.99 | **Yes** |
|
||
|
||
### 10.2 Competitive Positioning
|
||
|
||
| Competitor | Users | What They Do Best | What They Miss |
|
||
|-----------|-------|-------------------|----------------|
|
||
| **Tiimo** (App of Year 2025) | 3M+ | Visual timeline, AI planner, neurodivergent-first | No timers, no pre-warnings, no cooking/utility use case |
|
||
| **Structured** | Millions | Beautiful timeline, Pomodoro, Live Activities | No AI, no pre-warnings, no linked timers, no travel |
|
||
| **Alarmy** | 75M | Wake-up missions, sleep/mood tracking | Wake-up only, no countdowns, no routines, no pre-warnings |
|
||
| **TickTick** | 10M+ | All-in-one (tasks + Pomodoro + habits) | Timer is secondary, overwhelming UI, no cascade |
|
||
| **Forest** | 2M+ paid | Gamified focus, real tree planting | Focus-only, no alarms, no routines |
|
||
| **Routinery** | 1M+ | Step-by-step timed routines | Routine-only, no general timers, no calendar |
|
||
| **Due** | Premium | Persistent re-reminders | iOS/Mac only, dated UI, no routines or urgency |
|
||
| **Reclaim.ai** | Growing | AI auto-scheduling, focus time protection | Calendar-only, no timer/alarm, $8/mo |
|
||
| **Motion** | Growing | AI project + calendar management | Over-engineered, $19/mo, no simple timers |
|
||
|
||
**ChronoMind's moat:** No existing app combines pre-warning cascades + urgency intelligence + visual timeline + routines + linked timers + Pomodoro + neurodivergent design in a single, beautiful, offline-first web app. The closest competitors (Tiimo, Structured) are planners that happen to have timers. ChronoMind is a **timer that happens to be intelligent** — a fundamentally different approach.
|
||
|
||
**Key insight from research:** Tiimo winning App of the Year 2025 proves that visual, gentle, AI-augmented time management is mainstream — not niche. ChronoMind should embrace this design philosophy from day one.
|
||
|
||
---
|
||
|
||
## 11. Monetization (Future — v1.1+)
|
||
|
||
ChronoMind is **free and open-source** for personal use. Potential future revenue:
|
||
|
||
| Tier | Price | Features |
|
||
|------|-------|----------|
|
||
| **Free** | $0 | All MVP + v1.0 features, unlimited timers, local storage, Pomodoro, routines |
|
||
| **Pro** | $3.99/mo or $29.99/yr | Cloud sync, calendar integration, custom sounds, AI reschedule, advanced stats |
|
||
| **Family** | $5.99/mo | Shared timers (up to 6 members), household coordination, family routines |
|
||
|
||
> **Pricing rationale:** Market range is $2.49/mo (Structured) to $5.99/mo (Tiimo). $3.99/mo is the sweet spot. Family tier replaces "Team" — household coordination is the stronger v2 monetization path than enterprise. Team/API access can be added later if demand emerges.
|
||
|
||
---
|
||
|
||
## 12. Success Metrics (MVP)
|
||
|
||
| Metric | Target | How to Measure |
|
||
|--------|--------|----------------|
|
||
| **PWA installs** | 100 in first month | Service worker registration |
|
||
| **Daily active users** | 50 | IndexedDB activity timestamp |
|
||
| **Timers created/week** | 500+ | In-app analytics |
|
||
| **Pre-warning engagement** | >60% of timers use cascade | Default-on, track opt-out |
|
||
| **Routine usage** | >20% of users create a routine | Feature adoption tracking |
|
||
| **Snooze rate** | <30% (means alarms are well-timed) | Snooze event tracking |
|
||
|
||
---
|
||
|
||
## 13. Development Phases
|
||
|
||
### Phase 1: MVP — Web PWA (2 weeks)
|
||
|
||
| Week | Deliverable |
|
||
|------|------------|
|
||
| Week 1 | Project setup (Next.js 16, TailwindCSS v4, shadcn/ui, Zustand + IndexedDB), timer engine, visual timeline dashboard, create alarm/countdown flow, pre-warning cascade logic |
|
||
| Week 2 | Urgency levels, notifications (Web Push + Service Worker), sounds (Web Audio), Pomodoro timer, quick timers, dark/light theme, PWA install (Serwist), tab title countdown |
|
||
|
||
### Phase 2: Intelligence + Polish (2 weeks)
|
||
|
||
| Week | Deliverable |
|
||
|------|------------|
|
||
| Week 3 | Routines, linked timers, NL input (chrono-node), contextual pre-warning messages, recurring timers |
|
||
| Week 4 | Focus mode, prep time, history + stats + streaks, categories/tags, neurodivergent mode (visual countdown rings), calendar .ics import |
|
||
|
||
### Phase 3: iOS + Apple Watch (3 weeks)
|
||
|
||
| Week | Deliverable |
|
||
|------|------------|
|
||
| Week 5 | iOS app scaffold (SwiftUI), data model (SwiftData/CoreData), timer engine port, notification scheduling (UNUserNotificationCenter) |
|
||
| Week 6 | Apple Watch complications + Live Activities, iOS widgets (WidgetKit), haptic pre-warnings |
|
||
| Week 7 | AI reschedule, adaptive snooze, calendar sync (EventKit), polish + TestFlight |
|
||
|
||
### Phase 4: Context & Expansion (4 weeks)
|
||
|
||
| Week | Deliverable |
|
||
|------|------------|
|
||
| Week 8-9 | Full calendar sync (Google/Apple/Outlook OAuth), location-based triggers, travel time estimates |
|
||
| Week 10-11 | macOS menu bar (SwiftUI), cloud sync (E2E encrypted), sleep integration, shared timers MVP |
|
||
|
||
---
|
||
|
||
## 14. Risk Assessment
|
||
|
||
| Risk | Severity | Mitigation |
|
||
|------|----------|------------|
|
||
| **PWA notification unreliability on iOS** | High | Tab title countdown as supplementary signal; aggressive testing on iOS Safari; native iOS app fast-follow in Phase 3 (week 5-7) |
|
||
| **Feature creep** — too many timer types | High | Strict MVP scope (alarm + countdown + Pomodoro only); add types based on usage data, not speculation |
|
||
| **AI costs** for NL input and suggestions | Medium | chrono-node (local) for MVP NL parsing; LLM only for complex queries in v2; no API costs for MVP |
|
||
| **Calendar sync complexity** (OAuth, token refresh) | Medium | Start with .ics import (read-only, zero OAuth) in v1.0; full OAuth sync deferred to v1.1 |
|
||
| **Competition from Tiimo/Structured adding pre-warnings** | Medium | Move fast; pre-warning cascade + urgency levels is non-trivial to implement well; ship MVP in 2 weeks |
|
||
| **User overwhelm** — too many options per timer | Medium | Smart defaults everywhere; progressive disclosure (simple → advanced); "quick timer" as primary entry point |
|
||
| **Service Worker killed by OS** | Medium | Periodic `setTimeout` checks (30s); `setInterval` poll in active tab; visible countdown in tab title; native app for critical reliability |
|
||
| **Neurodivergent design requires research** | Low | Study Tiimo's design patterns; consult ADHD/autism community; iterate based on feedback |
|
||
|
||
---
|
||
|
||
## 15. Open Questions
|
||
|
||
| # | Question | Decision Needed |
|
||
|---|----------|----------------|
|
||
| 1 | Should MVP include cloud sync or be 100% local? | **Decision: local-only MVP, cloud in v1.1** |
|
||
| 2 | Natural language parsing: local regex or LLM API? | **Decision: chrono-node (local) for MVP, optional LLM v2** |
|
||
| 3 | Should the main clock be analog, digital, or both? | **Decision: digital primary, analog option** |
|
||
| 4 | PWA notification reliability — is it good enough? | **Test: if <90% delivery, prioritize native iOS in Phase 3** |
|
||
| 5 | Should routines support branching (if/else steps)? | **Decision: linear-only MVP, branching v2** |
|
||
| 6 | Gamification: streaks only, or Forest-style planting? | **Decision: streaks + focus scores in v1.0; explore tree/garden metaphor based on user feedback** |
|
||
| 7 | Neurodivergent mode: separate toggle or default UX? | **Decision: design for neurodivergent by default (visual timers, gentle transitions); add "compact mode" for power users** |
|
||
| 8 | Calendar sync: read-only or two-way? | **Decision: read-only import (.ics) in v1.0; two-way sync in v1.1** |
|
||
|
||
---
|
||
|
||
## 16. Appendix: Naming
|
||
|
||
| Option | Pros | Cons |
|
||
|--------|------|------|
|
||
| **ChronoMind** | Unique, conveys "smart time" | Slightly long |
|
||
| **Cadence** | Implies rhythm, routine, timing; modern feel | Might be confused with music apps |
|
||
| **Headstart** | Captures prep-time / pre-warning essence | Common word, SEO challenge |
|
||
| **Prelude** | "Before the main event" — elegant, unique | Might sound too musical |
|
||
| **Nudge** | Friendly, approachable, describes pre-warnings well | Generic, already used by other products |
|
||
| **PreWarn** | Describes core feature | Too narrow |
|
||
| **TimeShift** | Cool, implies flexibility | Vague |
|
||
|
||
**Working name: ChronoMind** — subject to change. "Cadence" and "Headstart" are strong alternatives.
|
||
|
||
---
|
||
|
||
## 17. Summary
|
||
|
||
ChronoMind fills a real gap: the space between "dumb alarm" and "full calendar app." Every phone has a clock app, but none of them answer the question *"how do I make sure I'm prepared for what's coming?"*
|
||
|
||
**The 2026 market is ready for this:**
|
||
- AI scheduling is mainstream (Reclaim, Motion)
|
||
- Visual time management won App of the Year (Tiimo, 2025)
|
||
- Neurodivergent-first design wins mainstream users (3M+ Tiimo downloads)
|
||
- PWA tech is mature enough for MVP
|
||
- Wellness + productivity convergence demands intelligent time awareness
|
||
|
||
**Five core innovations:**
|
||
1. **Pre-warning cascade** — configurable multi-step escalation so you're never surprised
|
||
2. **Visual timeline** — see your entire day at a glance, Structured/Tiimo-style
|
||
3. **Urgency-aware intelligence** — the app understands that a flight and a laundry timer are fundamentally different
|
||
4. **Routines + linked timers** — timed sequences for morning routines, cooking, and multi-step workflows
|
||
5. **Neurodivergent-first design** — visual countdown rings, gentle transitions, time-blindness support
|
||
|
||
**Positioning:** Not a planner that has timers (Tiimo, Structured). A **timer that is intelligent** — purpose-built for time awareness, prep, and execution.
|
||
|
||
The MVP is achievable in 2 weeks as a web PWA with no backend dependency. iOS + Apple Watch follows in weeks 5-7. |