SnapMeet - Real-Time Screen Sharing & Chat Platform

A modern, lightweight screen sharing and real-time chat application designed for seamless collaboration. Built with cutting-edge web technologies including React 19, TypeScript, WebRTC (PeerJS), and Socket.IO for instant peer-to-peer connections.

📋 Table of Contents

• Features
• Tech Stack
• System Requirements
• Installation
• Running the Application
• Usage Guide
• Browser Compatibility
• Architecture
• Troubleshooting
• Contributing
• License

✨ Features

Core Communication Features

• 🚀 Instant Room Creation: Generate unique 8-character codes for instant room setup
• 👥 Multi-user Support: Support for multiple concurrent participants in a single room
• 🖥️ HD Screen Sharing: Crystal-clear screen sharing via WebRTC with PeerJS
• 💬 Real-time Chat: Instant messaging with all room participants
• 🎯 User Presence Awareness: See who's in the room with live status indicators

User Experience Features

• 🎨 Dark/Light Theme: Seamless theme switching with persistent user preference
• 📱 Responsive Design: Optimized for desktop, tablet, and mobile browsers
• 🔗 One-Click Invite: Copy and share room links instantly
• 👤 Custom User Names: Set and change your display name anytime
• ⚡ Smooth Animations: Polished UI with smooth transitions and interactions

Advanced Features

• 🔐 Peer-to-Peer Security: Direct connections between users with no data relay
• 📊 Real-time Synchronization: Instant state updates across all participants
• 🎛️ Advanced Controls: Comprehensive meeting controls for professional use
• 🌐 Cross-platform Support: Works across major browsers and operating systems
• 🔄 Graceful Disconnection: Automatic cleanup on network interruptions

🛠️ Tech Stack

Frontend

• Framework: React 19 with TypeScript for type-safe development
• Routing: TanStack Router for powerful client-side routing
• State Management: Zustand for lightweight, performant state handling
• Styling: TailwindCSS 4.0 for utility-first CSS and responsive design
• UI Components: Shadcn UI & Radix UI for accessible, customizable components
• Icons: Lucide React for beautiful, consistent iconography
• Build Tool: Vite for lightning-fast development and optimized production builds

Backend & Communication

• WebRTC: PeerJS for simplified peer-to-peer connections
• Signaling: Socket.IO for real-time bidirectional communication
• Server: Node.js-based signaling server for connection management

Development Tools

• Package Manager: pnpm for fast, reliable dependency management
• Code Quality: ESLint for code linting and Prettier for code formatting
• Testing: Vitest for unit testing framework
• Version Control: Git for source code management

💻 System Requirements

Minimum Requirements

• OS: Windows 10+, macOS 10.14+, or Linux (Ubuntu 18.04+)
• Node.js: Version 18.0.0 or higher
• RAM: 2GB minimum
• Disk Space: 500MB for installation and dependencies

Recommended Requirements

• Node.js: Version 20.0.0 or higher
• RAM: 4GB or more
• Bandwidth: 1Mbps minimum for screen sharing
• Browser: Latest Chrome, Edge, or Firefox

Package Manager

• pnpm: 10.27.0 or higher (recommended)
• Or: npm 9.0.0+ or yarn 3.0.0+

📦 Installation

Step 1: Clone the Repository

git clone https://github.com/rumsan/snapmeet.git
cd snapmeet-ul

Step 2: Install Dependencies

Using pnpm (recommended for faster installation):

pnpm install

Or using npm:

npm install

Or using yarn:

yarn install

Step 3: Verify Installation

Ensure all dependencies are installed correctly:

pnpm list peerjs socket.io-client zustand

You should see the version numbers for each package.

🚀 Running the Application

The application requires two separate servers to function properly:

1. Frontend Development Server - Serves the React application (port 3000)
2. Signaling Server - Manages WebRTC connections (port 3001)

Option 1: Run Both Servers Together (Recommended)

Run both servers simultaneously with a single command:

pnpm dev:all

This uses concurrently to start both services. Watch for confirmation that both are running:

• Frontend: Local: http://localhost:3000
• Backend: Signaling server running on port 3001

Option 2: Run Servers Separately

For more control and easier debugging:

Terminal 1 - Start Frontend:

pnpm dev

Terminal 2 - Start Signaling Server (in the same project directory):

pnpm server

Option 3: Production Build

Build and preview the application:

# Build for production
pnpm build

# Preview the production build
pnpm preview

Access the Application

Once both servers are running, open your browser and navigate to:

http://localhost:3000

You should see the SnapMeet home page with the name entry form.

📚 Usage Guide

Getting Started with a Room

Creating a New Meeting Room

1. Enter Your Name

   • Type your preferred display name in the input field (2-50 characters)
   • This name will be visible to all participants

2. Create Room

   • Click the "Go Live" button
   • A unique 8-character room code is generated automatically
   • You'll be taken to the meeting room

3. Invite Participants

   • Click the copy icon next to the room code to copy the full URL
   • Share the link via email, chat, or messaging app
   • Participants can either use the link directly or enter the room code manually

Joining an Existing Room

1. Enter Your Name

   • Type your display name in the input field

2. Enter Room Code

   • Paste or type the 8-character room code in the "Join Existing Room" field
   • Or click a shared link to auto-fill the room code

3. Join the Meeting

   • Click the "Join Room" button
   • Wait for peer connections to establish (usually 1-2 seconds)
   • You'll see other participants appear in the participants panel

During a Meeting

Screen Sharing

Starting Screen Share:

1. Click the "Share Screen" button in the meeting controls
2. A browser dialog will appear showing available screens/windows
3. Select the screen or window you want to share
4. Click "Share" in the dialog

Sharing System Audio (Chrome/Edge only):

• When selecting what to share, check the "Share tab audio" checkbox
• This allows others to hear audio from your shared content

Stopping Screen Share:

• Click the "Stop Sharing" button
• Your screen will immediately stop being shared to others

Viewing Other Participants

View Another User's Screen:

1. Look at the Users List panel on the right side
2. Click on a user's card or avatar
3. Their screen stream will appear in the main display area
4. Switch between users by clicking different user cards

View All Participants:

• The users list shows all connected participants
• Green status indicator means they're active
• Click on any user to see their screen (if they're sharing)

Real-time Chat

Send a Chat Message:

1. Click the "Chat" button in the meeting controls
2. The chat panel will open on the right side
3. Type your message in the input field
4. Press Enter or click "Send"
5. Your message appears instantly for all participants

Chat Features:

• Messages show sender's name and timestamp
• Automatic scrolling to latest messages
• Message history persists during the session
• Works independently of screen sharing status

Meeting Controls

Available Controls:

• Share Screen: Toggle screen sharing on/off
• Chat: Open/close the chat panel
• Mute/Unmute: Control your audio (if implemented)
• Settings: Access room and display settings
• Copy Link: Share the room URL with others
• Leave Room: Exit the meeting and return home

Managing Your Display Name

• Click the "Change Name" button during a meeting
• Enter your new display name
• Click "Update"
• Your new name appears immediately to all participants

Leaving a Room

1. Click the "Leave" button in the meeting controls
2. Confirm the action if prompted
3. All connections will be closed
4. You'll return to the home page
5. Other participants will see you as disconnected

Keyboard Shortcuts

• Enter: Send chat message
• Esc: Close chat panel or exit room (confirm required)
• Tab: Navigate through UI elements

🌐 Browser Compatibility

Fully Supported Browsers

• ✅ Chrome 60+ (Recommended for audio sharing)
• ✅ Edge 79+ (Recommended for audio sharing)
• ✅ Firefox 55+
• ✅ Safari 13+ (Limited audio sharing)

Feature Support by Browser

Feature	Chrome	Edge	Firefox	Safari
Screen Sharing	✅ Full	✅ Full	✅ Full	✅ Limited
Audio Sharing	✅ Yes	✅ Yes	✅ Limited	⚠️ No
Chat	✅ Yes	✅ Yes	✅ Yes	✅ Yes
WebRTC	✅ Yes	✅ Yes	✅ Yes	✅ Yes

Browser-Specific Notes

Chrome/Edge (Recommended):

• Best overall compatibility
• Support for sharing tab audio
• Hardware acceleration for smooth playback

Firefox:

• Full feature support
• Select "Share entire screen" for system audio

Safari:

• May require screen recording permission
• Audio sharing not supported
• Works for receiving shared screens

Enabling Permissions

Most browsers require permission for screen sharing:

1. When you click "Share Screen", a permission dialog appears
2. Click "Allow" or "Share" to grant permission
3. Permissions are remembered per session

If blocked, check your browser settings:

• Chrome: Settings → Privacy and security → Site settings → Screen sharing
• Firefox: about:preferences#privacy → "Permissions" → Screen Sharing
• Edge: Settings → Privacy, search, and services → Site permissions
• Safari: System Preferences → Security & Privacy → Screen Recording

🏗️ Architecture

High-Level Architecture

┌─────────────────────────────────────────────┐
│          Browser (Frontend)                 │
│  ┌──────────────────────────────────────┐  │
│  │      React 19 Application           │  │
│  │  ┌────────────────────────────────┐ │  │
│  │  │  TanStack Router              │ │  │
│  │  │  - Home Page                  │ │  │
│  │  │  - Meeting Room               │ │  │
│  │  └────────────────────────────────┘ │  │
│  │  ┌────────────────────────────────┐ │  │
│  │  │  Zustand Store                │ │  │
│  │  │  - Room State                 │ │  │
│  │  │  - User Management            │ │  │
│  │  │  - Chat Messages              │ │  │
│  │  └────────────────────────────────┘ │  │
│  └──────────────────────────────────────┘  │
│                                             │
│  ┌──────────────────────────────────────┐  │
│  │  WebRTC & Communication             │  │
│  │  ┌────────────────────────────────┐ │  │
│  │  │  PeerJS (WebRTC)              │ │  │
│  │  │  - P2P Screen Sharing         │ │  │
│  │  │  - Direct Media Streams       │ │  │
│  │  └────────────────────────────────┘ │  │
│  │  ┌────────────────────────────────┐ │  │
│  │  │  Socket.IO Client             │ │  │
│  │  │  - Signaling Messages         │ │  │
│  │  │  - Chat Relay                 │ │  │
│  │  │  - User Events                │ │  │
│  │  └────────────────────────────────┘ │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
              ↓ WebSocket ↓
┌─────────────────────────────────────────────┐
│    Node.js Signaling Server                 │
│  ┌──────────────────────────────────────┐  │
│  │  Socket.IO Server                   │  │
│  │  - Room Management                  │  │
│  │  - User Registration                │  │
│  │  - Signaling Messages Relay         │  │
│  │  - Chat Message Broadcasting        │  │
│  │  - Connection Events                │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Data Flow

1. Room Creation: User creates room → Frontend generates ID → Server stores room → Client joins
2. User Joining: Client sends join request → Server adds to room → Broadcasts to others
3. Screen Sharing: User requests share → Browser captures screen → Offers via PeerJS → Others connect
4. Chat Message: User types message → Socket.IO sends to server → Server broadcasts to all participants
5. Screen Viewing: User clicks participant → Establishes peer connection → Stream received

File Structure

src/
├── routes/              # TanStack Router routes
│   ├── __root.tsx       # Root layout
│   ├── index.tsx        # Home page
│   └── room.$roomId.tsx # Meeting room
├── components/          # React components
│   ├── meeting-room.tsx # Main room component
│   ├── meeting-controls.tsx # Control buttons
│   ├── chat-panel.tsx   # Chat interface
│   ├── users-list.tsx   # Participants list
│   └── ui/              # Shadcn UI components
├── hooks/              # Custom React hooks
│   ├── use-webrtc.ts    # WebRTC peer management
│   └── use-screen-share.ts # Screen sharing logic
├── stores/             # Zustand state management
│   └── meeting-store.ts # Central application state
├── lib/                # Utilities
│   ├── utils.ts
│   └── user-storage.ts
└── styles/             # Styling
    └── css/

🐛 Troubleshooting

Common Issues and Solutions

Issue: Cannot Connect to Server

Symptom: "Connection refused" or "Cannot reach server" message

Solutions:

1. Verify both servers are running:

   pnpm dev:all

2. Check ports 3000 and 3001 are not in use:

   # macOS/Linux
   lsof -i :3000
   lsof -i :3001
   
   # Windows
   netstat -ano | findstr :3000

3. Firewall may be blocking connections - temporarily disable or add exceptions

4. If using VPN, try disconnecting and reconnecting

Issue: Screen Sharing Not Working

Symptom: "Share Screen" button is disabled or fails to start

Solutions:

1. Verify your browser supports screen sharing (see Browser Compatibility)
2. Grant permission when prompted:
   • Look for permission dialog from browser
   • Click "Allow" or "Share"
3. Update your browser to the latest version
4. Try a different browser (Chrome/Edge recommended)
5. Restart the browser if permissions were previously denied

Issue: Other Participants Can't See My Screen

Symptom: Button shows "sharing" but others see black screen

Solutions:

1. Verify WebRTC connection established (check console for errors)
2. Try stopping and restarting screen share
3. Check network connection - ensure good bandwidth
4. Look for errors in browser console (F12 → Console tab)
5. Try with a different window/screen
6. Restart both servers and rejoin room

Issue: Chat Not Sending or Receiving

Symptom: Messages disappear or don't appear for others

Solutions:

1. Check Socket.IO connection status
2. Verify signaling server is running: pnpm server
3. Try refreshing the page (F5)
4. Check browser console for errors
5. Ensure message input is not empty
6. Restart the signaling server

Issue: Connection Keeps Dropping

Symptom: Frequently disconnected or "reconnecting..." message

Solutions:

1. Check your internet connection stability
2. Move closer to WiFi router if on WiFi
3. Restart both servers
4. Rejoin the room
5. Check browser console for timeout errors
6. Verify no network bandwidth throttling

Issue: High Latency or Slow Performance

Symptom: Delayed screen updates, laggy interactions

Solutions:

1. Close other bandwidth-consuming applications
2. Reduce the number of concurrent connections
3. Ensure adequate internet bandwidth (1Mbps minimum)
4. Try lowering browser hardware acceleration settings
5. Restart the browser and servers
6. Check for peer connection errors in console

Issue: "Permission Denied" for Screen Sharing

Symptom: Permission dialog appears but permission is blocked

Solutions:

1. Check browser privacy settings for screen sharing permissions
2. Enable screen sharing permission for localhost:3000:
   • Chrome: Settings → Privacy and security → Site settings → Screen sharing
3. Make sure you're not in a private/incognito window (may restrict permissions)
4. Restart the browser
5. Try a different browser

Issue: Browser Console Errors

Symptom: Red errors appearing in browser console (F12)

Solutions:

1. Note the error message completely
2. Check if it's a non-critical warning (many are safe to ignore)
3. Critical errors typically prevent feature functionality
4. Common errors:
   • "Cannot read property of undefined": Refresh the page
   • "WebSocket connection failed": Check signaling server
   • "PeerJS error": Try restarting the room

Getting Help

If issues persist:

1. Check the Console: Press F12 → Console tab for error messages
2. Review Network Tab: F12 → Network tab to check connection status
3. Verify Setup: Ensure all steps in Installation and Running sections are complete
4. Test Locally First: Verify it works on localhost before troubleshooting further
5. Browser DevTools: Use browser DevTools to debug WebRTC connections

🤝 Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

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

---

🎯 Roadmap

Coming Soon

• 📹 Video calls with audio/video
• 📁 File sharing between participants
• 🎨 Collaborative whiteboard
• 🔴 Session recording
• 🔐 Room passwords and access control
• 📈 Usage analytics and statistics

Future Features

• 👤 User authentication and profiles
• 💾 Message history and persistence
• 🎬 Screen recording with transcoding
• 🌍 Multi-language support
• 📱 Mobile native applications
• 🔔 Desktop notifications

---

Happy collaborating with SnapMeet! 🚀