---
title: "Personal Habit Tracker"
brief: "A mobile habit-tracking app with three key screens: Today view, Habit detail, and Weekly stats."
version: 1
planId: "plan_2051dec8ca3d4644"
source: "agent-native-plan"
---

<RichText id="blk-goal" title="Goal">

Build a focused mobile habit tracker that helps users build and sustain daily routines. The app prioritizes **speed of daily check-in** — opening the app and marking habits done should take under 10 seconds. Secondary goals are streak motivation and lightweight weekly reflection.

The three screens cover the full loop: see what's due today, understand a habit's history, and review the week at a glance.

</RichText>

<RichText id="blk-screens" title="Key Screens">

### Today View

The home screen. Shows a progress summary card (habits completed / total, current streak) and a scrollable list of today's habits grouped by status. Tapping a habit row opens the detail screen; tapping the check circle toggles completion without navigating away.

### Habit Detail

Shows the habit's name, description, schedule (daily / weekdays / custom days), and a 30-day completion calendar heatmap. Users can edit the habit, archive it, or delete it from here. The streak and longest-streak counters live here rather than cluttering the Today view.

/

### Weekly Stats

A summary of the past 7 days across all habits. A bar chart shows daily completion percentage. Below it, each habit gets a row with its 7-day completion dots (filled = done, empty = missed, gray = not scheduled). Helps users spot which habits are slipping before a streak breaks.

</RichText>

<RichText id="blk-datamodel" title="Data Model">

Three core tables:

`habits` — one row per habit the user has created.

- `id` UUID PK
- `name` text (e.g. "Morning run")
- `description` text optional
- `schedule` jsonb — `{ type: 'daily' | 'weekdays' | 'custom', days?: number[] }`
- `color` text — hex accent for the row/heatmap
- `archived_at` timestamp nullable
- `created_at` timestamp

`completions` — one row per habit-day the user marked done.

- `id` UUID PK
- `habit_id` FK → habits
- `completed_on` date (local calendar date, not UTC timestamp)
- `created_at` timestamp

`users` — standard auth row; habits are scoped by `user_id` FK on the habits table.

Derived values (streak, weekly %, heatmap) are computed at query time — no denormalized counters to keep in sync.

</RichText>

<RichText id="blk-impl" title="Implementation Plan">

### Phase 1 — Data layer

Create the `habits` and `completions` tables with RLS policies scoped to `auth.uid()`. Write three actions: `list-habits-today` (returns habits due today + today's completions joined), `toggle-completion` (upsert/delete a completions row), and `get-habit-detail` (habit row + last 30 completions).

### Phase 2 — Today View

Build the mobile screen with a progress summary card at the top. The card recomputes on every `toggle-completion` call via query invalidation. Habit rows use an optimistic toggle so the check feels instant. Group habits into "remaining" and "done" sections dynamically.

### Phase 3 — Habit Detail

Render the 30-day heatmap as a 5×6 grid of colored squares (filled = done, empty = missed, gray = not scheduled). Streak is computed from the completions array in descending date order. Edit form uses the same `upsert-habit` action as creation.

### Phase 4 — Weekly Stats

Add a `get-weekly-stats` action that returns, for each of the last 7 days, the count of scheduled habits and the count completed. The bar chart maps completion % per day. The per-habit dot row is a simple 7-element array of `done | missed | not-scheduled`.

### Phase 5 — Polish

Add haptic feedback on completion toggle (mobile web vibration API). Add an empty state for new users with a prompt to add their first habit. Ensure the schedule picker handles timezone-safe local dates throughout.

</RichText>

<Callout id="blk-open" title="Open Questions" tone="info">

1. **Notifications** — Should the app send a daily reminder push? Requires a service worker + push subscription flow not covered in this plan. \[REGISTRY-EDIT-OK\]
2. **Timezone handling** — `completed_on` stores the user's local date. If the user travels, do we adjust retroactively or lock to the device timezone at completion time? Recommend locking at completion time.
3. **Habit ordering** — Manual drag-to-reorder vs. auto-sort (incomplete first)? Auto-sort is simpler and keeps the most actionable habits at the top.

</Callout>

<Checklist
  id="blk-checklist"
  title="Implementation Checklist"
  items={[
    {
      id: "c1",
      label: "Create habits and completions tables with RLS",
      checked: true,
    },
    {
      id: "c2",
      label: "list-habits-today action",
    },
    {
      id: "c3",
      label: "toggle-completion action (optimistic UI)",
    },
    {
      id: "c4",
      label: "Today View screen with progress card",
    },
    {
      id: "c5",
      label: "get-habit-detail action + 30-day heatmap",
    },
    {
      id: "c6",
      label: "Habit Detail screen with edit/archive",
    },
    {
      id: "c7",
      label: "get-weekly-stats action",
    },
    {
      id: "c8",
      label: "Weekly Stats screen with bar chart + dot rows",
    },
    {
      id: "c9",
      label: "Empty state for new users",
    },
    {
      id: "c10",
      label: "Timezone-safe local date handling throughout",
    },
  ]}
/>