|
1 | | -# CLAUDE.md |
| 1 | +# CLAUDE Development Notes |
2 | 2 |
|
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 3 | +This document contains extended guidance for working on Pulse. Codex will also use these instructions for additional context. |
4 | 4 |
|
5 | | -## Development Commands |
| 5 | +## Local Development Workflow |
6 | 6 |
|
7 | | -**Development workflow:** |
8 | | -```bash |
9 | | -pnpm dev # Start dev server with Turbopack |
10 | | -pnpm build # Build for production |
11 | | -pnpm lint # Run ESLint |
12 | | -``` |
| 7 | +- Install dependencies with `pnpm install`. |
| 8 | +- Start the application locally with `pnpm dev`. |
| 9 | +- Build for production with `pnpm build`. |
13 | 10 |
|
14 | | -**Database management:** |
15 | | -```bash |
16 | | -supabase start # Start local Supabase |
17 | | -supabase stop # Stop local Supabase |
18 | | -supabase db reset # Reset local database (CONFIRM BEFORE RUNNING) |
19 | | -supabase status # Check Supabase status |
20 | | -``` |
21 | | - |
22 | | -**Testing commands:** |
23 | | -```bash |
24 | | -pnpm test # Run unit tests in watch mode |
25 | | -pnpm test:run # Run unit tests once |
26 | | -pnpm test:coverage # Run unit tests with coverage |
27 | | -pnpm test:e2e # Run Playwright E2E tests |
28 | | -pnpm test:e2e:ui # Run E2E tests with UI mode |
29 | | -pnpm test:e2e:debug # Run E2E tests in debug mode |
30 | | -``` |
| 11 | +### Supabase Local |
| 12 | +- `supabase start` — start the local Supabase instance. |
| 13 | +- `supabase stop` — stop the instance when not needed. |
| 14 | +- `supabase status` — check whether Supabase is running. |
| 15 | +- `supabase db reset` — **destroys local data. Confirm before running.** |
31 | 16 |
|
32 | 17 | ## Architecture Overview |
33 | 18 |
|
34 | | -### Application Structure |
35 | | -- **Next.js 15 App Router** with route groups: `(authenticated)` for protected routes, `admin` for admin-only areas |
36 | | -- **Supabase local development** - always confirm before running `supabase db reset` as it resets the database |
37 | | -- **Multi-step form flow** orchestrated by `WeeklyPulseForm` with screen-based progression |
38 | | -- **Dynamic questions system** with versioned questions supporting multiple types (text, textarea, number, multiple_choice, checkbox) |
| 19 | +Pulse uses Next.js 15 with the App Router. Key route groups are `(authenticated)` for user views and `admin` for administrative pages. Supabase authentication works on both the server and API routes through helper clients in `src/lib/supabase` (`server.ts`, `api.ts`, `middleware.ts`). |
| 20 | + |
| 21 | +Submissions are collected via the multi-step `WeeklyPulseForm`. Questions are versioned so that historical submissions retain their original questions. Track the time from `startTime` to form completion for analytics purposes. |
| 22 | + |
| 23 | +## Testing Tools |
39 | 24 |
|
40 | | -### Authentication & Authorization |
41 | | -- **Supabase SSR authentication** with three client types: |
42 | | - - Server: `/utils/supabase/server.ts` for server components |
43 | | - - API: `/utils/supabase/api.ts` for API routes |
44 | | - - Middleware: `/utils/supabase/middleware.ts` for route protection |
45 | | -- **Two-tier access control**: authenticated users vs admin users (`is_admin` flag) |
46 | | -- **Middleware-based route protection** in `/src/middleware.ts` |
| 25 | +- Unit tests: `pnpm test:run` |
| 26 | +- Coverage: `pnpm test:coverage` |
| 27 | +- End-to-end tests: `pnpm test:e2e` (requires MCP and local Supabase) |
| 28 | +- Debugging E2E tests: `pnpm test:e2e:debug` |
47 | 29 |
|
48 | | -### Database Schema |
49 | | -- **Versioned questions**: Questions use `parent_id` self-reference with version incrementing |
50 | | -- **Submission windows**: Friday 5PM opens → Monday 2PM due → Tuesday 5PM late cutoff |
51 | | -- **JSONB storage**: `additional_projects` in submissions, `answers` in submission_answers |
52 | | -- **Hierarchical data**: Comments with `parent_id`, questions with versioning |
| 30 | +## Important Notes |
53 | 31 |
|
54 | | -### Form Architecture |
55 | | -- **Screen components** in `/src/components/screens/` with consistent interfaces |
56 | | -- **Question-to-screen mapping**: Categories map to specialized screens (e.g., `primaryProject` → `ProjectSelectionScreen`) |
57 | | -- **Dynamic question rendering** falls back by question type |
58 | | -- **Form data structure**: Core submission data + `answers` object keyed by question ID |
| 32 | +- Follow modern Next.js 15 patterns (server actions, file-based routing). |
| 33 | +- Form validation occurs at the UI, API layer, and database constraints. |
| 34 | +- Refer to `docs/test-plan.md` for the full testing strategy and `docs/implementation.md` for architecture details. |
59 | 35 |
|
60 | | -### Testing Strategy |
61 | | -- **Unit tests**: Vitest with React Testing Library and jsdom |
62 | | -- **E2E tests**: Playwright with automatic dev server setup |
63 | | -- **Test utilities**: Supabase mocks in `/src/test-utils/` |
64 | 36 |
|
65 | 37 | ### Key Business Logic |
66 | | -- **Week calculations**: ISO week numbers with `date-fns` for consistency |
| 38 | + |
67 | 39 | - **Auto-sharing**: Submissions auto-shared with managers for NEXT_PUBLIC_COMPANY_EMAIL_DOMAIN emails |
68 | 40 | - **Streak calculation**: Configurable start week with exclusions for holidays |
69 | 41 | - **Late submission detection**: Based on submission window timing |
70 | 42 |
|
71 | | -### Component Patterns |
72 | | -- **Screen components**: Follow props pattern `{onNext, onBack, formData, setFormData, error}` |
73 | | -- **Admin components**: Modular structure in `/src/components/admin/` |
74 | | -- **UI components**: Radix UI-based components in `/src/components/ui/` |
75 | | - |
76 | | -### Important Notes |
77 | | -- Always use Next.js 15 latest practices, not older patterns |
78 | | -- Supabase local development - confirm before database resets |
79 | | -- Form validation happens at multiple levels: form, API, and database |
80 | | -- Time tracking from `startTime` to completion for analytics |
0 commit comments