# CLAUDE.md

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

## Project Overview

cog-socket is a platform for hosting jsPsych and Pavlovia experiments with multiplayer support using WebSockets. Built with SvelteKit, it supports both single-player and multiplayer psychological experiments.

## Development Commands

### Database
- `npm run db:start` - Start PostgreSQL server via Docker Compose
- `npm run db:push` - Push schema changes to database
- `npm run db:migrate` - Run database migrations
- `npm run db:studio` - Open Drizzle Studio for database management

### Development Server
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run preview` - Preview production build

### Multiplayer Server
- `npm run multiplayer:dev` - Start multiplayer server in watch mode
- `npm run multiplayer:start` - Start multiplayer server in production mode

### Testing & Quality
- `npm run test` - Run all tests (unit + e2e)
- `npm run test:unit` - Run unit tests with Vitest
- `npm run test:e2e` - Run end-to-end tests with Playwright
- `npm run check` - Run svelte-check for TypeScript checking
- `npm run lint` - Run linting (Prettier + ESLint)
- `npm run format` - Format code with Prettier

## Architecture Overview

### Database Schema (DrizzleORM + PostgreSQL)
- **Users**: Authentication with Lucia, supports admin/user roles
- **Experiments**: jsPsych or PsychoJS experiments with multiplayer flag
- **Sessions**: User authentication sessions
- **ExperimentSessions**: Individual experiment runs with status tracking

### Multiplayer System (Colyseus)
- **Standalone server**: Runs on separate port (8080) from main app
- **ExperimentRoom**: Manages participant queuing, state synchronization
- **Session management**: Handles participant connections, disconnections, and queuing
- **Real-time communication**: WebSocket-based experiment state sharing

### SvelteKit Structure
- **Routes**: 
  - `/experiment/[id]` - Single experiment management
  - `/public/multiplayer/run/[experimentId]` - Multiplayer experiment runner
  - `/public/run/[experimentId]` - Single-player experiment runner
  - `/api/experiments/[experimentId]` - Experiment API endpoints
- **Authentication**: Lucia-based session management with cookies
- **File handling**: S3 integration for experiment assets

### Key Components
- **ExperimentRoom.ts**: Core multiplayer room logic with participant management
- **ExperimentRoomState.ts**: Colyseus schema for synchronized state
- **colyseusServer.ts**: Multiplayer server setup and room management
- **sessionManager.ts**: Bridges SvelteKit app with Colyseus server

## Development Notes

### Multiplayer Development
- Multiplayer server runs independently on port 8080
- Experiments must have `multiplayer: true` flag in database
- Room capacity determined by `maxParticipants` field
- Queue system handles overflow participants

### Authentication
- Default admin user (admin/admin) created in development
- Session tokens stored in cookies, managed by Lucia
- Authentication middleware in `hooks.server.ts`

### Database Operations
- Use DrizzleORM for all database operations
- Schema defined in `src/lib/server/db/schema.ts`
- Migrations managed through drizzle-kit

### File Structure
- UI components in `src/lib/components/ui/` (bits-ui based)
- Server logic in `src/lib/server/`
- Route handlers follow SvelteKit conventions
- Multiplayer code isolated in `src/lib/server/multiplayer/`

## Testing Setup
- Unit tests: Vitest with Svelte browser testing
- E2E tests: Playwright
- TypeScript checking: svelte-check
- Linting: ESLint + Prettier with Svelte plugins