Skip to content

CLAUDE.md

Latest commit

 

History

History
296 lines (218 loc) · 10.2 KB

CLAUDE.md

File metadata and controls

296 lines (218 loc) · 10.2 KB
Raw

IMPORTANT FOR CLAUDE: Reference this file before implementing anything

Project: LIFT Digital Workplace Passport

Project Overview

A digital workplace passport application that helps neurodivergent employees document and share their workplace needs with line managers, promoting a more inclusive workplace environment. See ./docs/HITL_Docs/*.md for detailed requirements.

Tech Stack

  • Languages: TypeScript
  • Frameworks: Svelte 5, SvelteKit
  • Styling: TailwindCSS, DaisyUI
  • Data: Supabase (PostgreSQL)
  • Authentication: Supabase Magic Link
  • Testing: Vitest
  • Hosting: Vercel
  • Development: Local Supabase instance via Docker
  • Database Management: Supabase CLI

Code Style & Conventions

Import/Module Standards

  • Group imports by type: Svelte, external libraries, internal modules
  • Avoid wildcard imports
  • Use relative paths for imports within the same feature
  • Use absolute imports (@lib) for shared code

Naming Conventions

  • Functions: camelCase, verb-first (e.g., handleSubmit, fetchData)
  • Components: PascalCase (e.g., ProfileCard.svelte, LoginForm.svelte)
  • Stores: camelCase, noun-based (e.g., userStore, responsesStore)
  • Constants: UPPER_SNAKE_CASE for true constants, camelCase for config objects
  • Files: PascalCase for components, camelCase for utilities and services
  • Database columns: snake_case

Patterns to Follow

  • Flat component structure (all in /lib/components)
  • Ultra-minimal routing (just login and dashboard)
  • All categories in a single dashboard view with navigation
  • Context-based state management using Svelte 5's $state and setContext
  • SvelteKit server endpoints directly in page files
  • HTTP-only cookies for auth token storage
  • Component composition over inheritance
  • Prefer native form validation when possible

Development Workflow

  • Branch strategy: feature/fix-description
  • Commit message format: type(scope): description (e.g., feat(auth): add magic link login)
  • PR requirements: Reference issue, pass all checks, meet accessibility standards

Testing Strategy

  • Test framework: Vitest for all tests
  • Coverage requirements: 80% for critical paths
  • Test naming conventions: describe('Component/Function'), it('should do something')
  • Component testing: Vitest with @testing-library/svelte
  • API testing: Vitest with mocked Supabase client

See TESTING.md for detailed examples and best practices. Basic pattern for component tests:

import { describe, test, expect } from 'vitest';
import '@testing-library/jest-dom/vitest';
import { render, screen } from '@testing-library/svelte';
import MyComponent from './MyComponent.svelte';

describe('MyComponent', () => {
	test('renders correctly', () => {
		render(MyComponent);
		expect(screen.getByText('Expected text')).toBeInTheDocument();
	});
});

Environment Setup

  • Required environment variables (for local development):

    • PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
    • PUBLIC_SUPABASE_ANON_KEY (from supabase status)
    • SUPABASE_SERVICE_KEY (from supabase status, server-only)
    • EMAIL_SERVICE_KEY (for sending emails)

  • Supabase environments:

    • Development: Local Supabase instance via Docker
    • Production: Remote Supabase project
    • Local instance provides full Supabase stack including Auth, Database, Storage, and Email testing

  • Database seeding strategy:

    • supabase/seed.sql: Real questions data (auto-runs with supabase db reset)
    • supabase/test_data_seed.sql: Fake test data (run separately with script)
    • scripts/prod-seed-test-data.sh: Production script for adding test data

  • Setup commands:

    # Install dependencies
npm install

# Install Supabase CLI globally
npm install -g supabase

# Start local Supabase instance
supabase start

# Copy environment template and configure for local development
cp .env.example .env.local

# Set local environment variables:
# PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
# PUBLIC_SUPABASE_ANON_KEY=[anon key from supabase status]
# SUPABASE_SERVICE_KEY=[service_role key from supabase status]

Common Commands

# Build command
npm run build

# Test command
npm run test        # Run all Vitest tests
npm run test:unit   # Run tests in watch mode

# Lint command
npm run lint

# Check command
npm run check       # TypeScript type checking

# Development server
npm run dev

# Local Supabase commands
supabase start                  # Start local Supabase instance
supabase stop                   # Stop local Supabase instance
supabase status                 # Check status and get keys
supabase db reset               # Reset and seed local database with questions
supabase db push                # Push schema changes to production
./scripts/prod-run-migrations.sh     # Automated deployment using .env.production
                               # (run chmod +x ./scripts/prod-run-migrations.sh if needed)

# Database seeding commands
# Make scripts executable first (if needed)
chmod +x ./scripts/local-seed-test-data.sh
chmod +x ./scripts/local-delete-test-data.sh
chmod +x ./scripts/prod-seed-test-data.sh
chmod +x ./scripts/prod-run-migrations.sh

# Local development scripts
./scripts/local-seed-test-data.sh    # Add test data to local Supabase instance
./scripts/local-delete-test-data.sh  # Remove test data from local Supabase instance

# Production scripts
./scripts/prod-seed-test-data.sh     # Add test data to production (requires DATABASE_URL)
./scripts/prod-run-migrations.sh    # Run migrations on production

Architecture Patterns

State Management

  • Context-based architecture: Single AppState object in +layout.svelte with 16+ context providers
  • Granular state access: Use getContext('getProfileId') instead of traditional stores
  • View-based navigation: Four main views (dash, list, detail, email) with programmatic switching
  • Dev mode integration: Built-in development mode with test data and state inspection

Database Service Layer

  • Consistent return types: DbResult<T> and DbResultMany<T> for all database operations
  • Error handling: Custom DatabaseError class with structured error responses
  • Query patterns: Use QueryOptions and FilterOptions for consistent filtering
  • Versioning system: Responses and actions use version and is_latest fields for history tracking

Component Architecture

  • Semantic categorization: Components organized by purpose (cards, layouts, logic, ui, views)
  • Context dependency: Components access state via context, not props drilling
  • Styling approach: TailwindCSS 4.x with DaisyUI, custom component classes in app.css

Project Structure

Key directories and their purpose:

  • /src - Main source code
    • /routes - SvelteKit pages and layouts
      • +layout.svelte - Main app layout with centralized state management
      • +layout.server.ts - Auth protection
      • +page.svelte - Landing/login page
      • /dashboard/+page.svelte - Single dashboard with all categories
      • /auth/callback - Magic Link handling
    • /lib - Shared code
      • /components - All UI components (cards, layouts, logic, ui, views)
      • /services/database - Database service layer with consistent patterns
      • /types - TypeScript type definitions (appState, supabase)
      • utils.ts - Helper functions
  • /static - Static assets (images, icons)
  • /tests - Test files

Review Process Guidelines

Before submitting any code, ensure the following steps are completed:

  1. Run all lint, check and test commands

  2. Review outputs and iterate until all issues are resolved

  3. Assess compliance: For each standard, explicitly state ✅ or ❌ and explain why:

    • Code style and formatting
    • Naming conventions
    • Architecture patterns (refer to ARCHITECTURE.md)
    • Error handling
    • Test coverage
    • Documentation
    • Accessibility (WCAG 2.2 AA)

  4. Self-review checklist:

    • Code follows defined patterns
    • No debug/commented code
    • Error handling implemented
    • Tests written and passing
    • Documentation updated
    • Accessibility checked

Deployment (Vercel)

IMPORTANT: Production Deployment Rules

⚠️ CRITICAL: Production (https://lift02.vercel.app) is MANUALLY controlled. DO NOT deploy to production accidentally.

Deployment Commands:

# PREVIEW deployment (safe - for testing)
npm run deploy
# or
npx vercel

# PRODUCTION deployment (MANUAL ONLY - requires explicit approval)
npx vercel --prod

Safe Workflow:

  1. Work on feature branches (e.g., feat/implement_auth)
  2. Use npm run deploy to create preview deployments for testing
  3. Preview deployments get unique URLs like https://lift02-xyz123.vercel.app
  4. Only deploy to production after explicit approval
  5. Production is controlled from main branch only

Environment Variables Setup

Set these environment variables in Vercel dashboard (Settings > Environment Variables):

Required for application:

  • PUBLIC_SUPABASE_URL - Your production Supabase project URL
  • PUBLIC_SUPABASE_ANON_KEY - Your production Supabase anon key
  • SUPABASE_SERVICE_KEY - Your production Supabase service role key
  • EMAIL_SERVICE_KEY - For sending emails

Optional for test data seeding:

  • DATABASE_URL - Full PostgreSQL connection string (get from Supabase > Settings > Database)
    • Format: postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres

Seeding Test Data in Production

# After deploying to Vercel, if you want to add test data:
# 1. Set DATABASE_URL environment variable in Vercel
# 2. Run locally with production env vars, or
# 3. Use Vercel CLI: vercel env pull && ./scripts/prod-seed-test-data.sh

Known Issues & Workarounds

  • Supabase has limited support for transactions - use client-side data validation as additional protection
  • Magic Link emails may be delayed - implement clear user feedback about checking email
  • Refer to FUNCTIONAL.md and ARCHITECTURE.md for more details on implementation

References