PlanAhead

AI-powered productivity system — goal decomposition, smart focus timer, gamified momentum tracking.

PlanAhead transforms how you plan and execute. Set high-level goals, let AI break them into actionable milestones, run focused work sessions with a live AI coach, and level up through a momentum-based gamification system.

---

Features

• AI Goal Decomposition — Describe a goal, get a structured plan with milestones, tasks, time estimates, and priorities
• Smart Focus Timer — Pomodoro, Deep Work, or Sprint presets with a live AI coach that motivates and warns during sessions
• Momentum System — XP, levels, streaks, velocity charts. Your productivity earns progression across 5 tiers
• Next Best Action — AI analyzes all your goals and recommends the single highest-impact task to work on right now
• Goal Health Scoring — Every goal gets a live AI-calculated health score (0-100) based on progress, deadline, and effort
• Project Recovery — At-risk goals get an AI intervention: scope trimming, deadline adjustments, and a rescue narrative
• Weekly Reviews — Auto-generated weekly summaries with grades, celebrations, critique, and next-week priorities
• Voice Commands — Floating orb for speech-to-text goal creation, timer control, and coaching
• Multi-Provider AI — Primary/backup Gemini keys with automatic failover, cascading to Groq and OpenRouter
• Smart Notifications — Deadline alerts, health warnings, momentum nudges, and weekly review reminders

---

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router), React 19, TypeScript 5
Auth	Clerk (JWT) + Supabase (RLS)
Database	Supabase (PostgreSQL) with Row Level Security
AI	Google Gemini 2.5 Flash (primary/backup), Groq (Llama), OpenRouter (DeepSeek)
State	TanStack React Query, Zustand
UI	Tailwind CSS v4, shadcn/ui, Framer Motion, Recharts
Forms/Zod	React Hook Form, Zod v4
Voice	Web Speech API (SpeechRecognition + SpeechSynthesis)

---

Getting Started

Prerequisites

• Node.js 20+
• A Supabase project
• A Clerk application
• At least one Gemini API key (Google AI Studio)

1. Clone and install

git clone <repo-url>
cd plan-ahead
npm install

2. Environment variables

Copy .env.local.example and fill in your credentials:

# Required
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# AI — at least one required
PRIMARY_GEMINI_API_KEY=your_gemini_key
BACKUP_GEMINI_API_KEY=your_backup_gemini_key   # optional
GROQ_API_KEY=your_groq_key                     # optional
OPENROUTER_API_KEY=your_openrouter_key         # optional

3. Run database migrations

# Apply Supabase migrations
npx supabase db push
# or run migrations manually from supabase/migrations/

4. Start development

npm run dev

Open http://localhost:3000.

---

Project Structure

src/
├── app/
│   ├── (auth)/              # Landing, login, signup, onboarding
│   ├── (dashboard)/         # Dashboard, planner, focus, momentum
│   └── api/                 # All API routes (webhooks, AI, data)
├── components/
│   ├── ui/                  # shadcn/ui primitives
│   ├── dashboard/           # Dashboard widgets
│   ├── planner/             # Goal planner components
│   ├── voice/               # Voice orb
│   └── providers.tsx        # Root providers
├── hooks/
│   ├── queries/             # React Query hooks
│   ├── mutations/           # Mutation hooks
│   ├── use-auth.ts          # Auth wrapper
│   ├── use-speech.ts        # Speech recognition
│   └── use-focus-timer.ts   # Timer state (Zustand)
├── lib/
│   ├── api/                 # Service layer (goal, task, momentum, recovery)
│   ├── gemini.ts            # Raw fetch Gemini client (dual-key failover)
│   ├── ai-provider.ts       # Multi-provider cascade
│   └── supabase/            # Supabase clients (user + service role)
└── store/                   # Zustand stores

---

API Overview

Method	Route	Purpose
POST	/api/webhooks	Clerk user sync (Svix-verified)
GET	/api/health	System health check
POST	/api/goals/[id]/decompose	AI goal decomposition
POST	/api/goals/[id]/health	AI health score calculation
POST	/api/goals/[id]/recover	AI project recovery
PUT	/api/tasks/[id]/complete	Task completion + XP award
GET	/api/actions/next	AI next best action
POST	/api/focus/coach	Live AI coaching
POST	/api/reviews/weekly	AI weekly review
POST	/api/voice/intent	Voice command processing
GET	/api/momentum/stats	Momentum statistics
POST	/api/momentum/coach	AI momentum coach message

---

Scripts

npm run dev       # Start development server
npm run build     # Production build
npm start         # Start production server
npm run lint      # Lint source files
npm test          # Run tests

---

License

MIT