CLAUDE.md

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

Project Overview

"super! je lis" is a French educational platform for schools to order books and receive associated pedagogical questionnaires. Schools browse a catalog, order books via Amazon redirection, and immediately unlock downloadable PDF questionnaires.

Tech Stack: Next.js 16, React 19, TypeScript, Supabase (PostgreSQL + Auth), Tailwind CSS v4, Stripe (payments), Sentry (monitoring), PostHog (analytics), n8n (external automation).

Commands

# Development
pnpm dev              # Start dev server on http://localhost:3000

# Quality checks
pnpm typecheck        # TypeScript type checking
pnpm lint             # ESLint

# Testing
pnpm test             # Run Vitest in watch mode
pnpm test:run         # Run unit tests once
pnpm test:coverage    # Run with coverage report
pnpm test:e2e         # Run Playwright e2e tests
pnpm test:e2e:ui      # Run e2e with UI
pnpm test:e2e:headed  # Run e2e in headed browser
pnpm test:all         # Run unit + e2e tests

# Build
pnpm build            # Production build

# Stripe testing
pnpm stripe:listen    # Forward Stripe webhooks to localhost
pnpm stripe:trigger   # Trigger test checkout.session.completed event

Architecture

Directory Structure

src/
  app/                    # Next.js App Router pages
    (admin)/admin/        # Admin dashboard (role-protected)
    (auth)/               # Login/signup pages
    (dashboard)/dashboard/# User dashboard (authenticated)
    api/                  # API routes (order, webhook, stripe, health, metrics)
  components/
    providers/            # React context providers (PostHog, Theme)
    ui/                   # Reusable UI components (shadcn/ui style)
  lib/
    supabase/             # Supabase client configuration (client.ts, server.ts)
    auth.ts               # Auth helper (getUser, isAdmin)
    queries.ts            # Database queries with pagination
    validation.ts         # Input validation utilities
    rate-limit.ts         # In-memory rate limiting
    logger.ts             # Structured logging
    stripe.ts             # Stripe helpers
supabase/
  schema.sql              # Main database schema
  migrations/             # Database migrations
e2e/                      # Playwright e2e tests

Route Groups

• (auth) - Public authentication pages (login, signup)
• (dashboard) - Protected user pages (catalog, questionnaires, profile, billing)
• (admin) - Admin-only pages (books, questionnaires, schools, settings)

Data Model

Core tables with Row Level Security (RLS):

• schools - User profiles (extends auth.users)
• books - Book catalog with grade levels (CP, CE1, CE2, CM1, CM2)
• questionnaires - PDF questionnaires linked to books
• school_questionnaires - Junction table for unlocked questionnaires per school
• subscriptions - Stripe subscription data

Key Flows

1. Order Flow: User clicks "Commander" → API creates school_questionnaire entry → redirects to Amazon
2. Webhook Flow: n8n calls /api/webhook/questionnaire with book_id and school_id → creates/links questionnaire
3. Stripe Flow: Checkout → webhook → subscription record in database → customer portal

Environment Variables

Required variables (see .env.local.example):

NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, SUPABASE_SERVICE_ROLE_KEY
STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_*_PRICE_ID
N8N_WEBHOOK_URL, N8N_WEBHOOK_SECRET
NEXT_PUBLIC_SENTRY_DSN, NEXT_PUBLIC_POSTHOG_KEY

Testing

• Unit tests: src/**/*.test.{ts,tsx} using Vitest + Testing Library
• E2E tests: e2e/*.spec.ts using Playwright (Chromium only)
• Run single test file: pnpm test src/lib/utils.test.ts
• Run specific e2e: pnpm exec playwright test e2e/auth.spec.ts

Test setup in src/test/setup.ts mocks Supabase client globally.

Path Alias

@/* maps to ./src/* (configured in tsconfig.json)

Security

• CSP and security headers configured in next.config.ts
• Rate limiting on auth, checkout, and webhook endpoints
• Input validation via src/lib/validation.ts
• Webhook secrets verified with timing-safe comparison