Feat/403 webrtc live classrooms

[Chigybillionz]

PR Title

feat: add WebRTC live group classrooms

──────────────────────────────────────────────────────────────────────────────

PR Description

Summary

Implement synchronous classroom features with WebRTC audio/video, shared whiteboard, chat, breakout rooms, and session recording. Adds a WebSocket-based signaling service, dedicated classroom API routes, and modular frontend components for live group classes.

Issue

Closes #403

Root Cause

The platform lacked dedicated infrastructure for real-time synchronous classrooms. While useClassroomMedia.ts handled group WebRTC calls via HTTP polling, there was no WebSocket signaling service, no dedicated classroom routes, and the UI was a monolithic 500+ line component with no modular breakdown.

Solution Implemented

Built a complete live classroom system with three layers:

1. Backend Signaling — WebSocket-based SignalingService handles WebRTC offer/answer/ICE candidate exchange between participants in real-time, replacing HTTP polling for signaling
2. Backend Routes — Dedicated /api/classroom endpoints for session lifecycle (create, start, end), participant management (join, leave), breakout rooms, and recording metadata
3. Frontend Components — Modular classroom UI components extracted from the monolithic VirtualClassroom.tsx , plus an extended useWebRTC hook supporting group calls via mesh topology

Key Changes

• Created SignalingService class that manages room membership, participant presence, and WebRTC signaling via Socket.IO events ( classroom:join , classroom:offer , classroom:answer , classroom:ice-candidate , classroom:chat , classroom:whiteboard , classroom:media-state )
• Created classroom session routes with full CRUD, join/leave, breakout room management, recording start/stop, and playback URL retrieval
• Extended useWebRTC hook with groupMode flag that enables mesh topology group calls, Socket.IO-based signaling, and participant tracking
• Created 5 modular classroom UI components: VideoGrid , MediaControls , BreakoutRooms , ClassroomChat , SessionRecording
• Initialized signaling service in backend entry point and mounted classroom routes at /api/classroom and /api/v1/classroom
• Added 18 unit tests covering classroom routes and signaling service

Affected Files

• backend/src/services/signaling/signalingService.ts — WebSocket signaling service for WebRTC
• backend/src/routes/classroom.ts — Dedicated classroom session API routes
• backend/src/index.ts — Mounted classroom routes + initialized signaling service
• frontend/src/hooks/useWebRTC.ts — Extended with group call support and Socket.IO signaling
• frontend/src/components/classroom/VideoGrid.tsx — Modular video grid with adaptive layout
• frontend/src/components/classroom/MediaControls.tsx — Camera, mic, screen share, recording, live, hand raise
• frontend/src/components/classroom/BreakoutRooms.tsx — Breakout room creation and management
• frontend/src/components/classroom/ClassroomChat.tsx — Chat with emoji reactions and file sharing
• frontend/src/components/classroom/SessionRecording.tsx — Recording start/stop with playback
• frontend/src/components/classroom/index.ts — Barrel exports
• backend/src/tests/classroomRoutes.test.ts — Unit tests for classroom routes
• backend/src/tests/signalingService.test.ts — Unit tests for signaling service

Trade-offs / Considerations

• Mesh topology: The group call uses full-mesh (each participant connects to every other). This scales well for small classes (<20 participants) but would need an SFU (Selective Forwarding Unit) for larger sessions.
• In-memory storage: Classroom sessions and signaling rooms are stored in-memory. In production, these should be persisted to Redis or a database for horizontal scaling.
• Backward compatibility: The existing VirtualClassroom.tsx and useClassroomMedia.ts remain untouched. The new modular components are additive and can be adopted incrementally.
• Signaling transport: The signaling service uses Socket.IO (WebSocket with fallback). The existing HTTP polling in useCollaborationSession.ts continues to work for non-WebRTC features.

Testing

• 18 unit tests pass for classroom routes and signaling service
• TypeScript typecheck passes for all new files (no new errors beyond pre-existing)
• Existing test suite not regressed

// bash
cd backend && npx jest src/tests/classroomRoutes.test.ts src/tests/signalingService.test.ts --no-coverage

CI Verification

• TypeScript typecheck: ✅ No new errors in new files
• Tests: ✅ 18/18 pass
• Lint: Not run locally (eslint not installed; CI handles gracefully with || echo "No linter configured" )
• Build: Not run locally (requires full npm ci ; CI runs npm run build -w backend and npm run build -w frontend )

Please kindly review this task. If there are any corrections, improvements, adjustments, or merge conflicts that you notice regarding my implementation, I'd really appreciate your feedback. I'd also love to hear your overall review of my work on this branch.

Thank you!