HabitFlow

A modern, full-featured habit tracking and productivity application built with React, TypeScript, and Vite. Includes a multi-mode timer (stopwatch/countdown/intervals), achievements, AI insights, analytics, exports, social/messaging, integrations with Google/Notion/Slack/Spotify/Fit, and email + TOTP MFA authentication. Ships as a Vite web app, a Capacitor Android wrapper, and a static landing page. Backend is Supabase (Postgres + Edge Functions) with Cloudflare Turnstile bot protection.

We follow a simplified two-branch flow:

• main — Production-ready code (protected)
• docs/*, feat/*, chore/*, fix/* — short-lived branches off main, squash-merged via PR

📖 See CONTRIBUTING.md for the workflow details.

• ⚛️ React 18 — Concurrent rendering
• 📘 TypeScript (strict) — Type safety end-to-end
• ⚡ Vite 6 — Fast HMR and builds

• 🐻 Zustand 5 — Lightweight state with persistence (8 global stores + 8 domain stores)
• 🗄️ Supabase — Postgres + Auth + Storage + Edge Functions (the only data layer)
• 🚀 React Router 7 — Declarative routing

• 📝 React Hook Form — Performant, flexible forms
• ✅ Zod 3 — TypeScript-first schema validation

• 🎨 Tailwind CSS 3 — Utility-first, with dark mode
• 🎬 Framer Motion — Animations
• 🧱 dnd-kit — Accessible drag-and-drop
• 📊 Recharts — Charts and analytics
• 🍞 react-hot-toast — Notifications
• 📄 html2canvas + jspdf — Premium exports

• 🔐 Supabase Auth — Email/password + JWT sessions
• 🛡️ Custom TOTP MFA — In src/lib/auth/mfa.ts
• 🤖 Cloudflare Turnstile — Bot protection on auth gateway
• 🪵 Sentry 10 — Error monitoring (opt-in via VITE_ENABLE_SENTRY)

• 🧪 Vitest 4 — Unit + component tests (jsdom)
• 🧩 React Testing Library — Component tests
• ♿ jest-axe — Accessibility assertions
• 🎭 Playwright — E2E tests (Firefox)
• 📏 ESLint 9 — Flat config, with @ts-nocheck debt awareness
• ✨ Prettier 3 — Formatter with Tailwind plugin
• 🐶 Husky 9 — Pre-commit hook (installed via npm run prepare)

• 📅 date-fns — Date utilities
• 🔧 Custom Hooks — useDebounce, useLocalStorage, etc.
• 📁 Path Aliases — @/ maps to src/

Feature-sliced architecture — domain code lives in src/features/<domain>/, cross-domain primitives in src/shared/ and the classic shared layers. See docs/ARCHITECTURE.md for the full architecture guide, dependency rules, and testing policy.

.
├── src/
│   ├── features/       # Domain features (timer, social, tasks, habits,
│   │                   #   categories, today, integrations, auth,
│   │                   #   accessibility, onboarding)
│   ├── shared/         # Cross-domain UI primitives + layout shell
│   ├── lib/            # Framework-free logic (auth, storage, security, env, errors)
│   ├── store/          # Global persisted Zustand stores
│   ├── pages/          # Routing composition
│   ├── hooks/ utils/ schemas/ types/ constants/
│   ├── __tests__/      # Cross-cutting tests only
│   ├── App.tsx         # Main App component
│   └── main.tsx        # Application entry point
├── e2e/                # Playwright specs (Firefox)
├── scripts/            # Codegen tooling (leagues → constants)
├── public/             # Static assets
├── index.html          # HTML template
└── vite.config.ts      # Vite configuration

• Node.js v20+
• npm v10+
• A Supabase project (for the backend)
• Cloudflare Turnstile site key (for auth bot protection)

# Install dependencies
npm ci

# Copy env template and fill in your values
cp .env.example .env

# Start the dev server (validates env on boot)
npm run dev

# Typecheck + production build
npm run build

# Preview the production build locally
npm run preview

All VITE_* variables are validated at module load time by src/lib/env.ts. Required vars throw in production; optional vars warn and fall through.

In production, missing required vars throw on import — the build fails fast. In development, missing required vars log to the console and fall back to placeholders so the dev server can boot.

Imports use the @/ alias (mapped to src/ in both tsconfig and vite.config.ts):

// Instead of
import Component from '../../../components/Component'

// You can use
import Component from '@/components/Component'

npm test              # Vitest in watch mode
npm run test:coverage # Vitest with v8 coverage report
npm run test:e2e      # Playwright (Firefox; install via `npx playwright install firefox`)

Tests are colocated with their subjects in __tests__/ directories. Two cross-cutting suites live in src/__tests__/. See docs/ARCHITECTURE.md for the testing policy and known-debt caveats.

npm run build

The build runs tsc --noEmit first, then Vite. Output is in dist/, ready to be deployed to any static hosting service.

The app is configured for dual-target deployment — both kept intentionally:

• Vercel — vercel.json at the repo root
• Netlify — netlify.toml at the repo root

Both build the SPA statically; the Supabase backend is a separate concern managed in the Supabase dashboard.

See CONTRIBUTING.md for setup, branching strategy, commit conventions, and the PR process.

MIT