91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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 |