Describe your idea. Get the spec your AI agent builds from.

# Build Blueprint: ChainKeeper

## 1. Product Summary

A focused daily habit tracker built around one principle: **don't break the chain**. Users create habits, check them off each day, and watch a calendar fill with streaks. The product optimizes for the single daily ritual — open app, tap to complete, feel progress.

**Core value:** Frictionless daily check-in + visceral streak visualization.

**MVP scope (in):**
- Email/password + Google auth
- Create/edit/archive habits (name, color, icon, schedule)
- One-tap daily completion (and undo)
- Streak calendar (month grid, current streak, longest streak)
- Daily completion stats per habit
- Local timezone-correct day boundaries

**Out of scope (v1):** Social/sharing, reminders/push notifications, paid tiers, analytics dashboards, multi-device real-time sync conflicts (last-write-wins is fine).

**Success metric:** D7 retention — % of users who check in at least once on day 7.

---

## 2. Tech Stack

| Layer | Choice | One-line justification |
|---|---|---|
| Framework | **Next.js 14 (App Router) + TypeScript** | One codebase for UI + API routes; fast to ship and deploy. |
| Styling | **Tailwind CSS + shadcn/ui** | Production-quality components without design overhead. |
| Database | **PostgreSQL (Supabase)** | Relational data (habits ↔ completions) with hosted auth included. |
| ORM | **Prisma** | Type-safe queries that match the data model exactly. |
| Auth | **Supabase Auth** | Email + Google OAuth out of the box; no custom session code. |
| State/Data | **TanStack Query** | Optimistic check-offs with cache rollback on failure. |
| Date logic | **date-fns + date-fns-tz** | Correct timezone-aware day boundaries. |
| Hosting | **Vercel** | Zero-config Next.js deploys. |

---

## 3. Data Model

Use Prisma with PostgreSQL. Store completion **dates** as `DATE` (no time) computed in the user's timezone.

```prisma
model User {
  id         String   @id @default(uuid())
  email      String   @unique
  timezone   String   @default("UTC") // IANA, e.g. "America/New_York"
  createdAt  DateTime @default(now())
  habits     Habit[]
}

model Habit {
  id          String   @id @default(uuid())
  userId      String
  name        String
  color       String   @default("#22c55e") // hex
  icon        String   @default("check")   // lucide icon name
  // schedule: which weekdays it's "due". Bitmask or array.
  activeDays  Int[]    @default([0,1,2,3,4,5,6]) // 0=Sun..6=Sat
  archivedAt  DateTime?
  createdAt   DateTime @default(now())
  sortOrder   Int      @default(0)

  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  completions Completion[]

  @@index([userId, archivedAt])
}

model Completion {
  id        String   @id @default(uuid())
  habitId   String
  date      DateTime @db.Date // the local calendar day completed
  createdAt DateTime @default(now())

  habit     Habit    @relation(fields: [habitId], references: [id], onDelete: Cascade)

  @@unique([habitId, date]) // one completion per habit per day
  @@index([habitId, date])
}
```

**Key rules:**
- A habit is "complete today" if a `Completion` row exists for `(habitId, today-in-user-tz)`.
- **Streak** = consecutive *scheduled* days (per `activeDays`) ending today (or yesterday if today not yet complete) with a completion. Days not scheduled are skipped, not breaks.
- Undo = delete the completion row.

---

## 4. Screens & UX

### 4.1 Today (home, default route `/`)
The core daily screen. A vertical list of today's habits.
- Each row: large circular check button (left), habit name + current streak ("🔥 12"), color accent.
- **Tap circle → instant fill animation + haptic** (optimistic). Tap again to undo.
- Top: date header ("Tuesday, March 4") + a one-line summary ("2 of 3 done today").
- Empty state: "Add your first habit" CTA → big and friendly.
- Habits not scheduled today are hidden by default (toggle "Show all").

### 4.2 Habit Detail (`/habit/[id]`)
- **Streak calendar**: month grid; completed days filled with habit color, today outlined, scheduled-but-missed days faintly marked.
- Month navigation (prev/next, no future).
- Stats row: Current streak · Longest streak · Total completions · Completion rate (last 30 scheduled days).
- Edit/Archive buttons.

### 4.3 Create / Edit Habit (`/habit/new`, modal or page)
- Name (required), color picker (8 presets), icon picker (12 lucide icons), schedule (weekday toggles, default all).
- Save → return to Today.

### 4.4 Auth (`/login`)
- Email/password + "Continue with Google". On first login, capture timezone via `Intl.DateTimeFormat().resolvedOptions().timeZone` and save to User.

**Design tone:** calm, minimal, lots of whitespace, one bold accent per habit color. Mobile-first (most check-ins happen on phone). Big tap targets (min 56px).

---

## 5. API / Server Logic

Use Next.js Route Handlers under `/app/api`. All endpoints require an authenticated Supabase session; scope every query by `userId`.

### Endpoints

```
GET    /api/habits
       → list active habits + today's completion status + current streak
POST   /api/habits
       → { name, color, icon, activeDays } → create
PATCH  /api/habits/:id
       → update fields (name/color/icon/activeDays/sortOrder)
DELETE /api/habits/:id
       → soft delete (set archivedAt)

POST   /api/habits/:id/toggle
       → { date: "YYYY-MM-DD" } → upsert/delete completion (idempotent)
       → returns new streak + completion state

GET    /api/habits/:id/calendar?month=YYYY-MM
       → completions for month + per-month stats

GET    /api/habits/:id/stats
       → currentStreak, longestStreak, totalCompletions, rate30
```

### Critical server logic

**Day boundary:** Always derive "today" from the *user's stored timezone*, not server time. Compute via date-fns-tz: `formatInTimeZone(new Date(), user.timezone, 'yyyy-MM-dd')`. Reject toggle requests for future dates.

**Toggle (idempotent):**
```ts
// pseudocode
const existing = await findCompletion(habitId, date);
if (existing) await deleteCompletion(existing.id);
else await createCompletion(habitId, date);
return computeStreak(habitId);
```

**Streak computation** (the heart of the product):
```ts
function computeCurrentStreak(habit, completions, today): number {
  const doneSet = new Set(completions.map(c => c.date)); // 'yyyy-MM-dd'
  let streak = 0;
  let cursor = today;
  // if today isn't done yet but is scheduled, start from yesterday
  if (isScheduled(habit, today) && !doneSet.has(today)) cursor = prevDay(today);
  while (true) {
    if (!isScheduled(habit, cursor)) { cursor = prevDay(cursor); continue; }
    if (doneSet.has(cursor)) { streak++; cursor = prevDay(cursor); }
    else break;
  }
  return streak;
}
```
`longestStreak` = max run found scanning all completions with the same scheduled-day rules. Cache nothing in v1 — recompute on read (datasets are tiny).

**Validation:** Zod schemas on every body. Reject habits with empty name or invalid hex/activeDays.

---

## 6. Build Order

Ship in vertical slices; each step should be runnable.

1. **Scaffold** — Next.js + TS + Tailwind + shadcn/ui. Configure Prisma + Supabase Postgres. Run first migration.
2. **Auth** — Supabase Auth (email + Google). Protected layout, `/login` page, capture timezone on first sign-in.
3. **Habit CRUD** — API routes + create/edit form + Prisma. Verify in DB.
4. **Today screen** — list habits, optimistic toggle via TanStack Query, undo, "X of Y done" summary.
5. **Streak engine** — implement `computeCurrentStreak` + `longestStreak` with unit tests (test timezone edges + skipped scheduled days). Surface streaks on Today.
6. **Habit detail + calendar** — month grid, navigation, stats row, archive.
7. **Polish** — animations (check fill), empty states, mobile layout pass, error toasts on failed toggles.
8. **Deploy** — Vercel + Supabase prod env. Smoke test full flow.

**Test focus:** streak math is the riskiest logic — write unit tests first for it (DST boundary, week with off-days, undo, gap).

---

## 7. Handoff Prompt

> Build **ChainKeeper**, a daily habit tracker, per this blueprint. Stack: **Next.js 14 App Router + TypeScript, Tailwind + shadcn/ui, Prisma + Supabase (Postgres + Auth), TanStack Query, date-fns/date-fns-tz, deploy to Vercel.**
>
> Implement in the build order given. Start by scaffolding the project, configuring Prisma with the exact schema in section 3, and running the migration. Set up Supabase Auth with email/password and Google; on first sign-in store the user's IANA timezone from the browser.
>
> Build the API route handlers in section 5 exactly as specified. Every query MUST be scoped to the authenticated `userId`. All "today" calculations MUST use the user's stored timezone via date-fns-tz — never raw server time. The `toggle` endpoint must be idempotent (upsert/delete a `Completion` for a given local date) and reject future dates.
>
> Implement the streak engine from section 5: streaks count consecutive *scheduled* days (per `activeDays`), skipping unscheduled days, and treat an incomplete-but-scheduled today as not breaking the streak (count from yesterday). Write unit tests covering DST transitions, off-day weeks, undo, and gaps before building UI on top.
>
> Build the four screens in section 4 mobile-first. The Today screen uses optimistic updates with TanStack Query and rolls back on error with a toast. The Habit Detail screen renders a month calendar grid filling completed days with the habit's color. Use shadcn/ui components and keep the design calm, minimal, with large (56px+) tap targets.
>
> Use Zod for all input validation. Use environment variables for all secrets; never hardcode keys. Deliver runnable code at each build step, ending with a Vercel deployment.