cog-socket/CLAUDE.md

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