DramaAdda - Real-Time Multiplayer Charades

A production-grade, real-time multiplayer charades game with WebRTC video streaming, interactive drawing canvas, and optimized WebSocket communication.

🎯 Features

🎮 Game Modes

📹 Video Mode - Act out words using your camera (WebRTC P2P)
🎨 Drawing Mode - Classic charades with real-time canvas
🔀 Hybrid Mode - Combine video and drawing simultaneously

⚡ Real-Time Multiplayer

WebSocket-based instant communication (<50ms latency)
Automatic reconnection with exponential backoff
Multiple rooms support with automatic cleanup
Live scoring and leaderboards
Progressive word hints

🎥 WebRTC Video Streaming

Peer-to-peer video connections (actor → all guessers)
Low latency streaming (<500ms)
Automatic fallback for restrictive networks
STUN/TURN server support

🎨 Interactive Drawing

Real-time synchronized canvas (Konva.js)
Touch-enabled for mobile devices
Stroke batching for smooth performance
Clear canvas & undo support

👤 Avatar System

DiceBear integration with 4 styles
16 unique character seeds
Avatars displayed in chat, header, and leaderboard

🏆 Smart Scoring

Early guess bonus (1st: +5, 2nd: +3, 3rd: +1)
Actor points for each correct guess
Real-time leaderboard updates
Attempt limits (3 wrong guesses max)

🏗️ Architecture

Technology Stack

Backend (Go)

Framework: Gin Web Framework
WebSocket: Gorilla WebSocket
Language: Go 1.21+
Communication: Real-time bidirectional WebSocket

Frontend (React)

Framework: React 19 + TypeScript
Build Tool: Vite
Styling: TailwindCSS
Canvas: Konva.js + React-Konva
WebRTC: Native WebRTC API
Avatars: DiceBear

Project Structure (Monorepo)

DramaAdda/
├── backend/                    # Go WebSocket server
│   ├── cmd/server/            # Application entry point
│   │   └── main.go           # Production-ready server
│   ├── internal/
│   │   ├── ws/               # WebSocket handlers
│   │   │   ├── hub.go       # Connection manager
│   │   │   ├── client.go    # Client handler
│   │   │   ├── room.go      # Game room logic
│   │   │   ├── game_logic.go # Game flow control
│   │   │   └── game_messages.go # Message types
│   │   └── game/            # Game mechanics
│   │       ├── words.go     # Word database
│   │       └── fuzzy.go     # Fuzzy matching
│   ├── data/
│   │   └── words.json       # Bollywood movies & phrases
│   ├── go.mod
│   └── go.sum
│
└── frontend/                  # React TypeScript app
    ├── src/
    │   ├── components/       # React components
    │   │   ├── Lobby.tsx    # Room & avatar selection
    │   │   ├── GameRoom.tsx # Main game container
    │   │   ├── ActorView.tsx # Actor's interface
    │   │   ├── GuesserView.tsx # Guesser's interface
    │   │   ├── DrawingCanvas.tsx # Konva drawing
    │   │   ├── VideoStream.tsx # WebRTC video
    │   │   ├── ChatBox.tsx  # Chat & guesses
    │   │   └── Leaderboard.tsx # Scores
    │   ├── services/
    │   │   ├── websocket.ts # WebSocket client
    │   │   └── webrtc.ts    # WebRTC manager
    │   ├── hooks/
    │   │   ├── useWebRTC.ts # WebRTC hook
    │   │   └── useMediaStream.ts # Camera hook
    │   └── types/
    │       └── game.ts      # TypeScript definitions
    ├── dist/                # Production build output
    ├── package.json
    └── vite.config.ts

🚀 Quick Start

Prerequisites

Go 1.21 or higher
Node.js 18 or higher
npm or yarn

Development Setup

1️⃣ Clone Repository

git clone https://github.com/YOUR_USERNAME/DramaAdda.git
cd DramaAdda

2️⃣ Start Backend Server

cd backend
go run cmd/server/main.go

Backend runs on http://localhost:8080

3️⃣ Start Frontend Development Server

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173

4️⃣ Play!

Open http://localhost:5173 in multiple browser tabs
Create or join a room
Select avatars and mark ready
Start the game!

🔧 Production Deployment

Environment Variables

Backend

PORT=8080                          # Server port
GIN_MODE=release                   # Gin mode (debug/release)
FRONTEND_URL=https://your-app.com  # Frontend URL for CORS
WORD_DB_PATH=./data/words.json     # Word database path

Frontend

VITE_WS_URL=wss://api.your-app.com/ws  # WebSocket backend URL

Build Commands

Backend (Render/Fly.io)

cd backend
go build -o server cmd/server/main.go
./server

Frontend (Vercel/Netlify)

cd frontend
npm run build
# Output: dist/

Deployment Platforms

Recommended Setup (Free Tier):

Backend: Render.com or Fly.io
Frontend: Vercel or Netlify

Both platforms support:

✅ Auto-deployment from GitHub
✅ Free SSL/HTTPS certificates
✅ Environment variables
✅ WebSocket support

🔌 Technical Features

Backend Optimizations

Memory Management

✅ Automatic room cleanup - Empty rooms cleaned every 5 minutes
✅ Goroutine leak prevention - Context-based cancellation for all long-running tasks
✅ Safe channel operations - Prevents panic on double-close
✅ Bounded buffers - 256-message buffer prevents memory bloat

Graceful Shutdown

✅ Signal handling - Responds to SIGINT/SIGTERM
✅ 30-second timeout - Graceful shutdown with configurable timeout
✅ Resource cleanup - All connections, goroutines, and timers properly terminated
✅ Hub-first shutdown - Ensures game logic stops before HTTP server

Connection Management

✅ HTTP timeouts - 15s read/write, 60s idle
✅ WebSocket timeouts - 10s write, 60s pong, 54s ping
✅ Message size limit - 1 MB maximum
✅ CORS middleware - Environment-based origin configuration

Performance

✅ Concurrent room handling - Read/Write locks for thread-safety
✅ Buffered broadcast - Non-blocking message distribution
✅ Timer optimization - Proper cleanup prevents memory leaks
✅ Health endpoint - /health for monitoring

Frontend Optimizations

WebSocket Resilience

✅ Auto-reconnection - Exponential backoff (max 5 attempts)
✅ Connection pooling - Single persistent connection per client
✅ Message queuing - Buffered send/receive
✅ Protocol detection - Auto ws:// or wss:// based on location

WebRTC Features

✅ P2P architecture - Actor broadcasts to all guessers
✅ ICE negotiation - Automatic STUN/TURN server usage
✅ Connection retry - Automatic reconnection on failure
✅ Fallback support - Falls back to drawing if video fails

Canvas Performance

✅ Stroke batching - 30ms intervals for smooth drawing
✅ Coordinate optimization - Integer coordinates
✅ Virtual DOM - Konva optimizations
✅ Touch support - Mobile-friendly

🎮 Game Flow

┌──────────────┐
│   LOBBY      │ Players join, select avatars, mark ready
└──────┬───────┘
       │
┌──────▼───────┐
│ GENRE SELECT │ Actor chooses genre or random
└──────┬───────┘
       │
┌──────▼───────┐
│ ACTING PHASE │ Actor performs (video/drawing/both)
└──────┬───────┘      Guessers submit guesses
       │              Progressive hints reveal
┌──────▼───────┐
│  ROUND END   │ Scores calculated, leaderboard updated
└──────┬───────┘
       │
       ├─────► Next Round (next player acts)
       │
┌──────▼───────┐
│  GAME OVER   │ Final scores, winner announced
└──────────────┘

Scoring System

Position	Base Points	Bonus	Total
1st to guess	10	+5	15
2nd to guess	10	+3	13
3rd to guess	10	+1	11
Others	10	0	10

Actor receives: 5 points per correct guesser

🔐 Security & Production Features

Security

✅ CORS protection with environment-based allowlist
✅ Input validation (room ID, username)
✅ Message size limits (1 MB max)
✅ Rate limiting via channel buffers
✅ No XSS vulnerabilities (React auto-escaping)

Monitoring

✅ Health check endpoint: GET /health
✅ Real-time client/room count
✅ Structured logging
✅ Error tracking

Scalability

✅ Multiple rooms simultaneously
✅ Automatic client reconnection
✅ Non-blocking broadcast architecture
✅ Efficient memory usage

📊 Performance Metrics

Metric	Value
WebSocket Latency	<50ms RTT
WebRTC Latency	<500ms (P2P)
Drawing Sync	~30ms
Message Throughput	256 buffered messages
Memory Usage	Auto-cleanup every 5 mins
Concurrent Rooms	Unlimited (memory-bound)

🧪 Testing

Manual Testing

# Terminal 1: Backend
cd backend && go run cmd/server/main.go

# Terminal 2: Frontend
cd frontend && npm run dev

# Browser: Open 3 tabs
# Tab 1: Create room as "Alice"
# Tab 2: Join room as "Bob"
# Tab 3: Join room as "Charlie"

# Test:
✅ All players mark ready
✅ Start game
✅ Actor draws → All see drawing
✅ Guesser types correct answer → Score updates
✅ Round completes → Leaderboard shows
✅ Game completes → Winner announced

WebRTC Testing

# Test video mode:
1. Enable camera permission
2. Select "Video Only" mode
3. Actor's video should appear on all guessers' screens
4. Audio is muted (by design)

🛠️ Development

Build Backend

cd backend
go build -o server cmd/server/main.go
./server

Build Frontend

cd frontend
npm run build
# Output: dist/

Run Tests

# Backend
cd backend
go test ./...

# Frontend
cd frontend
npm test

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow Go best practices for backend
Use TypeScript strict mode for frontend
Write meaningful commit messages
Test your changes locally
Update documentation as needed

📝 API Reference

WebSocket Messages

Client → Server

// Join room (sent automatically on connection)
{ type: "join", room_id: string, user_name: string }

// Mark ready
{ type: "ready" }

// Start game (host only)
{ type: "start_game", game_mode: "canvas" | "video" | "both" }

// Submit guess
{ type: "guess", guess: string }

// Drawing
{ type: "draw_batch", points: Point[] }
{ type: "clear_canvas" }

// WebRTC signaling
{ type: "webrtc_offer", sdp: RTCSessionDescription }
{ type: "webrtc_answer", sdp: RTCSessionDescription, to: string }
{ type: "ice_candidate", candidate: RTCIceCandidate, to: string }

Server → Client

// Game state
{ type: "turn_start", actor_id: string, round: number }
{ type: "word", word: string, category: string } // Actor only
{ type: "timer", seconds_left: number, hint: string }
{ type: "turn_end", word: string, leaderboard: Player[] }
{ type: "game_over", leaderboard: Player[] }

// Guess feedback
{ type: "correct_guess", client_id: string }
{ type: "guess_wrong", client_id: string, remaining_attempts: number }

// Drawing sync
{ type: "draw_batch", points: Point[], player_id: string }
{ type: "draw_clear", player_id: string }

// WebRTC
{ type: "webrtc_offer", sdp: RTCSessionDescription, from: string }
{ type: "webrtc_answer", sdp: RTCSessionDescription, from: string }
{ type: "ice_candidate", candidate: RTCIceCandidate, from: string }

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Gorilla WebSocket - Robust WebSocket implementation
Gin - Fast Go web framework
React - UI framework
Konva.js - Canvas library
DiceBear - Avatar generation
TailwindCSS - Utility-first CSS

🐛 Known Issues & Limitations

WebRTC behind strict firewalls: ~20-30% of users may need TURN server
Mobile canvas performance: Slightly slower on older devices
Free tier limitations: Backend sleeps after 15 mins on Render (first request takes ~30s)

🗺️ Roadmap

Add TURN server integration for better WebRTC connectivity
Implement persistent leaderboards (database)
Add sound effects and animations
Custom word lists upload
Team mode (2v2, 3v3)
Replay saved games
Mobile app (React Native)

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation