CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MigrainLog is a comprehensive migraine tracking application built with React 19, TypeScript, Vite, and Supabase. Users can track detailed migraine episodes including symptoms, triggers, medications, and contributing factors.

Development Commands

Running the Application

npm run dev              # Start development server (http://localhost:5173)
npm run build            # Build for production (includes TypeScript compilation)
npm run preview          # Preview production build locally

Code Quality

npm run lint             # Run ESLint
npx tsc -b              # Type-check without building

Testing

Unit Tests (Vitest)

npm run test            # Run tests in watch mode
npm run test:run        # Run tests once
npm run test:ui         # Run tests with UI
npm run test:coverage   # Run tests with coverage report

E2E Tests (Playwright)

npm run test:e2e                # Run E2E tests headless
npm run test:e2e:ui             # Run with interactive UI
npm run test:e2e:headed         # Run with visible browser
npm run test:e2e:debug          # Run with debugger
npm run test:e2e:chromium       # Run in Chromium only
npm run test:e2e:firefox        # Run in Firefox only
npm run test:e2e:webkit         # Run in WebKit only
npm run test:e2e:report         # View test report

Important: E2E tests require the dev server to be running. The Playwright config will automatically start it, but if you encounter issues, manually start the dev server first.

Tech Stack & Architecture

Core Technologies

Frontend: React 19 with TypeScript 5.9
Build Tool: Vite 7.2
Routing: TanStack Router (file-based, type-safe)
State Management: TanStack Query (React Query) for server state
Forms: TanStack Form with Zod validation
Backend: Supabase (PostgreSQL + Auth + RLS)
UI: Tailwind CSS v4 + shadcn/ui + Radix UI
Testing: Playwright (E2E) + Vitest (unit)

Path Aliases

The project uses TypeScript path aliases configured in

vite.config.ts

```
@/
```
maps to
```
src/
```
directory

Example:

import { supabase } from '@/lib/supabase'

Architecture Patterns

Authentication Flow

AuthContext (
```
src/contexts/AuthContext.tsx
```
) provides global auth state
useAuth hook wraps AuthContext for convenient access
Protected Routes: Routes under
```
src/routes/_authenticated/
```
require authentication
The
```
_authenticated.tsx
```
layout file uses a
```
beforeLoad
```
hook to check session and redirect to
```
/about
```
if not authenticated
Supabase handles authentication with email/password (social providers configurable)

Data Layer Architecture

Database: Single
```
episodes
```
table with Row Level Security (RLS)
Type Safety: Database types auto-generated in
```
src/types/database.ts
```
Episode Types: Domain types in
```
src/types/episode.ts
```
Data Access: Use TanStack Query hooks (
```
useEpisodesQuery
```
,
```
useCreateEpisodeMutation
```
, etc.)
Supabase Client: Singleton instance in
```
src/lib/supabase.ts
```

Routing Structure (TanStack Router)

The application uses file-based routing with TanStack Router:

src/routes/
├── __root.tsx                          # Root layout with AuthProvider
├── _authenticated.tsx                  # Auth layout (requires login)
├── _authenticated/
│   ├── index.tsx                       # Dashboard (/)
│   ├── episodes.tsx                    # Episode list
│   ├── episodes/$episodeId.tsx         # Episode detail/edit
│   └── analysis.tsx                    # Data visualization
├── about.tsx                           # Public about page
├── login.tsx                           # Login page
└── signup.tsx                          # Signup page

Important: The route tree is auto-generated by the TanStack Router plugin into

src/routeTree.gen.ts

. Never edit this file manually.

Form Handling Pattern

Forms use TanStack Form with Zod validation:

Define Zod schema in
```
src/utils/validation.ts
```
Create form with
```
useForm
```
hook from
```
@tanstack/react-form
```

Use

zodFieldValidator

from

src/utils/zodValidator.ts

for validation

Use shadcn/ui form components with
```
FormFieldContext
```
Handle submission with TanStack Query mutations

Example pattern from

EpisodeForm.tsx

const form = useForm({
  defaultValues: initialData,
  onSubmit: async ({ value }) => {
    await createMutation.mutateAsync(value);
  },
  validators: {
    onChange: episodeSchema,
  },
});

Episode Data Model

Episodes track comprehensive migraine data:

Basic Info: start_time, end_time, severity (1-10)
Arrays: pain_location[], symptoms[], triggers[]
JSONB: medications (array of objects with name, dosage, time_taken, effectiveness)
Optional: notes, contributing_factors (sleep, hydration, weather, stress)

The database schema includes:

GIN indexes on array/JSONB columns for efficient queries
Validation functions for valid enum values
Auto-updating
```
updated_at
```
trigger
```
episode_stats
```
view for analytics

Database & Environment Setup

Environment Variables

Copy

.env.example

.env

and fill in:

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Get these from Supabase Dashboard → Settings → API

Database Migration

Run

supabase/migrations/001_create_episodes.sql

via:

Supabase Dashboard → SQL Editor, or
Supabase CLI:
```
supabase db push
```

The migration creates:

```
episodes
```
table with RLS policies
Validation functions for pain_location, symptoms, triggers
Indexes for query performance
```
episode_stats
```
view
Auto-updating
```
updated_at
```
trigger

Row Level Security (RLS)

All episode data is user-scoped via RLS policies:

Users can only SELECT/INSERT/UPDATE/DELETE their own episodes
Enforced at database level via
```
user_id = auth.uid()
```
checks
This is critical for multi-tenant security

Key Components & Patterns

shadcn/ui Integration

Components are in
```
src/components/ui/
```
Installed via
```
npx shadcn@latest add <component>
```
Configuration in
```
components.json
```
Use the
```
cn()
```
utility from
```
@/lib/utils
```
for conditional classes

TanStack Query Usage

Query client configured in
```
src/lib/queryClient.ts
```
Query hooks in
```
src/hooks/useEpisodesQuery.ts
```
Use
```
invalidateQueries
```
after mutations to refresh data
Queries are automatically cached and deduplicated

Date Handling

Database stores dates as
```
TIMESTAMPTZ
```
Forms use string inputs (datetime-local format)
Convert between Date and string when transforming data
Use
```
date-fns
```
library for formatting (installed)

Testing Guidelines

E2E Test Utilities

Reusable helpers in

tests/utils/

```
auth-helpers.ts
```
: Login/signup helpers
```
test-data.ts
```
: Shared test data
```
assertions.ts
```
: Custom assertions

Test Organization

Auth tests:
```
tests/auth.spec.ts
```
Episode tests:
```
tests/episodes.spec.ts
```
Use Page Object pattern for complex page interactions

Common Patterns & Conventions

Type Safety

All database queries are typed via
```
Database
```
type from
```
@/types/database
```
Episode domain types in
```
@/types/episode
```
separate from DB types
Transform DB types to domain types when needed
Avoid
```
any
```
type - use
```
unknown
```
or proper typing

Error Handling

Supabase operations return
```
{ data, error }
```
- always check error
TanStack Query mutations handle errors via
```
onError
```
callback
Display errors to users via toast/alert components

Component Organization

src/components/
├── ui/              # shadcn/ui primitives (Button, Input, etc.)
├── episodes/        # Episode-specific components
├── layout/          # Layout components (Header, Footer)
└── ...             # Feature-specific directories