# 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.