Skip to content

README.md

Latest commit

 

History

History
174 lines (147 loc) · 5.37 KB

README.md

File metadata and controls

174 lines (147 loc) · 5.37 KB
Raw

Server runs on http://localhost:3000

Features Implemented

Phase 1: Server Infrastructure ✅

  • Custom HTTP + Socket.io server
  • Redis adapter (pub/sub for scaling)
  • JWT authentication middleware
  • Ping/pong heartbeat

Phase 2: Redis Service Layer ✅

  • Room state management (status, mode, timerEndTime, activeProblemId, maxCapacity)
  • User presence tracking (Redis Sets)
  • Room capacity enforcement
  • Media state persistence
  • Typing users with 3-second TTL
  • Socket-to-user mapping

Phase 3: Socket Event Handlers ✅

Presence:

  • join_room - Capacity check, emits room_error if full
  • leave_room - Cleanup and broadcast
  • disconnect - Full cleanup
  • toggle_media - Media state with Redis persistence

Timer:

  • timer_start - Server-side completion with setTimeout
  • timer_pause - Calculate remaining time
  • timer_reset - Clear state
  • timer_complete event - Broadcasts when timer hits 0
  • Analytics stub: recordSessionToDatabase()

Collaboration:

  • problem_changed - Updates activeProblemId, broadcasts sync
  • cursor_move - Volatile emit for high frequency
  • Yjs signaling (sync_step_1, sync_step_2, update)

Chat:

  • send_message - Timestamp, broadcast, persistence stub
  • typing_start - 3-second TTL in Redis
  • typing_stop - Broadcast

Phase 4: REST API ✅

  • GET /api/rooms - List active public rooms
  • GET /api/rooms?mode=solo - Filter by mode
  • POST /api/rooms - Create room (all 4 modes supported)

API Testing

Health Check

curl http://localhost:3000/health

List Rooms

curl http://localhost:3000/api/rooms
curl "http://localhost:3000/api/rooms?mode=solo"

Create Room (requires JWT)

curl -X POST http://localhost:3000/api/rooms \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"mode\":\"solo\",\"isPublic\":true,\"maxCapacity\":5}"

Run Test Script

powershell -ExecutionPolicy Bypass -File test-api.ps1

WebSocket Events

Client → Server

  • ping - Heartbeat
  • join_room(roomId) - Join with capacity check
  • leave_room(roomId) - Leave room
  • toggle_media({ roomId, type, enabled }) - Toggle mic/cam
  • timer_start({ roomId, duration, type }) - Start timer
  • timer_pause({ roomId }) - Pause timer
  • timer_reset({ roomId }) - Reset timer
  • problem_changed({ roomId, problemId }) - Change active problem
  • cursor_move({ roomId, line, column }) - Update cursor
  • send_message({ roomId, message }) - Send chat
  • typing_start({ roomId }) - Start typing
  • yjs_sync_step_1/2, yjs_update - Yjs CRDT sync

Server → Client

  • pong - Heartbeat response
  • room_state({ roomId, state, users }) - Current state
  • room_error({ message }) - Room full or error
  • user_joined({ userId, socketId }) - User joined
  • user_left({ userId, socketId }) - User left
  • media_state_changed({ userId, micOn, camOn }) - Media update
  • timer_sync({ state, endTime, duration, remainingTime }) - Timer state
  • timer_complete({ type, duration }) - Timer finished
  • active_problem_sync({ problemId, changedBy }) - Problem changed
  • cursor_update({ userId, line, column, color }) - Cursor moved
  • new_message({ userId, message, timestamp }) - New chat
  • typing_indicator({ userId, isTyping }) - Typing status
  • yjs_sync_step_1/2, yjs_update - Yjs sync

Architecture

server.ts (Entry Point)
├── Express App (REST API)
│   └── /api/rooms (GET, POST)
└── Socket.io Server (WebSocket)
    ├── Auth Middleware (JWT)
    ├── Redis Adapter (Scaling)
    └── Event Handlers
        ├── presence.handler.ts
        ├── timer.handler.ts
        ├── chat.handler.ts
        └── collaboration.handler.ts

File Structure

server/
├── server.ts                          # Entry point
├── src/
│   ├── config/
│   │   └── database.ts                # Shared Prisma instance
│   ├── services/
│   │   └── redis.service.ts           # All Redis operations
│   ├── socket/
│   │   ├── index.ts                   # Socket.io setup
│   │   ├── auth.middleware.ts         # JWT auth
│   │   └── handlers/
│   │       ├── presence.handler.ts    # Join/leave/media
│   │       ├── timer.handler.ts       # Timer with completion
│   │       ├── chat.handler.ts        # Chat with typing TTL
│   │       └── collaboration.handler.ts # Problem sync + Yjs
│   └── modules/
│       └── rooms/
│           ├── roomRoutes.ts
│           └── roomController.ts      # All modes + filter
├── .env                               # Environment config
├── test-api.ps1                       # API test script
└── README.md                          # This file

Environment Variables

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/studyroom
JWT_SECRET=your_jwt_secret_key_change_this_in_production
REDIS_HOST=localhost
REDIS_PORT=6379
CLIENT_URL=http://localhost:5173

Troubleshooting

Server won't start

  • Check if port 3000 is available
  • Verify Redis is running
  • Check .env configuration

Redis connection error

  • Start Redis: docker-compose -f docker-compose.redis.yml up -d
  • Or install Redis locally

Build errors

  • Run npx prisma generate
  • Run npm install