mid switch to Colyseum

CLAUDE.md

@@ -0,0 +1,91 @@
+# 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