Implemented real-time online debate platform with structured phases and AI judgment using WebSocket and WebRTC

[rixitgithub]

Implemented real-time online debate platform with structured phases and AI judgment using WebSocket and WebRTC

Description

This pull request introduces a comprehensive, real-time debate platform that enables human-vs-human debates with structured phases, integrated speech recognition, and AI-driven judgments. Users can now enjoy seamless live video/audio communication, automatic transcript generation, and detailed performance evaluation powered by the Gemini AI model.

These enhancements transform the debate application from a basic text-based system into an immersive, interactive platform with robust room management, clear turn indicators, and precise scoring feedback.

---

Context

Previously, the debate system lacked a dedicated environment for human-vs-human interactions. Users were unable to:

• Engage in live video/audio debates.
• Experience structured debate phases with enforced timers and clear turn management.
• Benefit from automatic transcript generation through speech recognition.
• Receive AI-based evaluation with detailed scoring and feedback.
• Create or join debate rooms easily through an intuitive UI.

This PR addresses these issues by:

• Implementing a real-time debate room using WebSocket and WebRTC.
• Establishing a structured debate flow with clearly defined phases and timers.
• Integrating the Web Speech API for real-time transcript generation.
• Utilizing AI to evaluate debate transcripts and provide objective scoring.
• Enhancing user experience through intuitive room creation/joining and visual feedback.

These changes create a robust, accessible, and engaging debate environment for users looking to improve their debating skills.

---

Changes Made

Frontend (React/TypeScript)

• Online Debate Room (OnlineDebateRoom.tsx):

  • Integrated WebSocket for real-time bidirectional communication between debaters.
  • Implemented WebRTC via RTCPeerConnection for seamless peer-to-peer video and audio streaming.
  • Added room management logic to ensure each room supports two debaters with proper cleanup on disconnection.

• Debate Phases & Timers:

  • Defined debate phases in a DebatePhase enum (e.g., Setup, OpeningFor, OpeningAgainst, CrossForQuestion, CrossAgainstAnswer, CrossAgainstQuestion, CrossForAnswer, ClosingFor, ClosingAgainst, Finished).
  • Employed useEffect hooks to manage timers and automatically transition phases.
  • Developed turn indication logic (isMyTurn) to highlight the active debater.

• Role Selection & Readiness (Setup Popup):

  • Enabled users to select their debate stance (for or against) with built-in checks to prevent duplicate role assignment.
  • Implemented a readiness mechanism using a toggleReady function via WebSocket.
  • Introduced a 3-second countdown once both debaters are ready to start the debate.

• Speech Recognition for Transcript Generation:

  • Integrated the Web Speech API (using SpeechRecognition or webkitSpeechRecognition) for real-time voice-to-text transcription.
  • Configured automatic start/stop of speech recognition based on the active phase and user turn.
  • Added a manual toggle for microphone control (displaying Mic/MicOff icons).

• Judgment System Integration:

  • Developed a submission workflow to send aggregated transcripts to the /api/submit-transcripts endpoint.
  • Utilized the JudgeDebateHumanVsHuman function to analyze transcripts using the Gemini AI model and return detailed scores and feedback.
  • Implemented polling logic to fetch judgment results every 2 seconds if awaiting the opponent’s submission.

• User Interface Enhancements:

  • Designed a visually engaging UI with avatars (sourced from local storage), countdown timers in MM:SS format, and animated turn indicators.
  • Created a comprehensive Judgment Popup to display detailed scoring, feedback, and the final verdict.

Backend (Go)

• Real-Time Communication:

  • Enhanced the backend WebsocketHandler to support real-time messaging and manage debate room sessions.
  • Integrated WebRTC signaling mechanisms to facilitate peer-to-peer streaming.

• API Endpoints & Data Management:

  • Modified API endpoints to process transcript submissions, incorporating parameters for timing, context, and debate phase.
  • Implemented the JudgeDebateHumanVsHuman function using the Gemini AI model to evaluate transcripts and generate structured feedback.
  • Updated data storage logic to persist transcripts and judgment results in MongoDB, with optional JSON file backups.
  • Ensured duplicate judgment prevention and seamless data conversion between frontend and backend formats.

• Security & Connection Handling:

  • Added authentication by including tokens from local storage in WebSocket connection requests.
  • Enforced room limits to two users and implemented robust disconnection and cleanup mechanisms.

---

How to Test

Setup

1. Backend:
   • Ensure MongoDB is running.
   • Start the backend with:

     go run cmd/server/main.go

2. Frontend:
   • Start the frontend with:

     npm run dev

   • The application should be accessible on localhost:5173.

Test Cases

• Debate Room Functionality:

  • Create a new debate room and verify that two users can join seamlessly.
  • Test live video/audio streaming between debaters using WebRTC.
  • Confirm that messages and phase transitions are handled in real time via WebSocket.

• Debate Phases & Timers:

  • Validate that each debate phase transitions automatically when its timer expires.
  • Check that the active debater is visually highlighted and that turn changes occur smoothly.

• Role Selection & Readiness:

  • Test the role selection process and ensure that duplicate roles cannot be assigned.
  • Verify the readiness indicators and the 3-second countdown before the debate starts.

• Speech Recognition & Transcript Submission:

  • Initiate speech recognition during a debate round and ensure transcripts are generated correctly.
  • Submit transcripts and verify that the AI judgment system returns detailed feedback and scores.

• UI and Visual Feedback:

  • Confirm that avatars, timers, and turn indicators render correctly on both desktop and mobile devices.
  • Test the judgment popup to ensure scores and feedback are displayed accurately.

• Edge Cases:

  • Test browser compatibility for speech recognition (Chrome recommended).
  • Simulate network disruptions to validate room cleanup and reconnection handling.

---

Video Comparison

Before Implementation:

Please refer to the attached video for a demonstration of the current implementation issues.

user_vs_user_before.mp4

After Implementation:

Please refer to the attached video for a demonstration of the new real-time debate platform in action.

user_vs_user_after.mp4

---

Screenshots

Feature	Screenshot
Debate Setup
Debate Room
Phase-wise Result
Final Result

---

Checklist

• Real-time communication via WebSocket and WebRTC tested
• Structured debate phases with timers verified for accurate transitions
• Role selection and readiness checks function correctly
• Speech recognition accurately captures and transcribes voice input
• AI-based judgment system provides detailed and unbiased feedback
• UI elements (avatars, timers, indicators) are responsive on all devices
• API endpoints handle all required parameters and data formats correctly

---

Reviewers

• Mentors: @keshav-nischal @ceilican

---

Additional Notes

• Speech recognition works best in Chrome and Edge browsers.
• The default phase timing has been tested for optimal debate flow.
• Future enhancements could include additional features like personalized debater profiles and advanced analytics.
• Feedback is welcome to further refine the debate experience.

---

Closes #72