AeThex-Connect/PHASE4-QUICK-START.md

# Phase 4: Voice & Video Calls - Quick Reference

## What Was Implemented

✅ **Database Schema**
- Extended `calls` table with WebRTC fields (type, sfu_room_id, recording_url, quality_stats)
- Extended `call_participants` table with media state and connection quality
- New `turn_credentials` table with auto-cleanup function

✅ **Backend Services**
- `callService.js` - Complete call lifecycle management (390+ lines)
  - initiateCall, answerCall, endCall
  - TURN credential generation with HMAC-SHA1
  - SFU room management (Mediasoup placeholder)
  - Media state updates
  - Call statistics and quality monitoring

✅ **API Routes** - 7 RESTful endpoints
- POST `/api/calls/initiate` - Start a call
- POST `/api/calls/:id/answer` - Answer call
- POST `/api/calls/:id/reject` - Reject call
- POST `/api/calls/:id/end` - End call
- PATCH `/api/calls/:id/media` - Update media state
- GET `/api/calls/turn-credentials` - Get TURN credentials
- GET `/api/calls/:id` - Get call details

✅ **WebSocket Signaling**
- call:offer, call:answer, call:ice-candidate
- call:incoming, call:ended
- call:participant-joined, call:participant-left
- call:media-state-changed

✅ **Frontend WebRTC Manager** (`utils/webrtc.js`)
- Peer connection management
- Local/remote stream handling
- Audio/video controls (toggle, mute)
- Screen sharing
- ICE candidate exchange
- Connection quality monitoring
- ~550 lines of WebRTC logic

✅ **Call React Component** (`components/Call/`)
- Full-featured call UI with controls
- Local and remote video display
- Call status indicators
- Media controls (mute, video, screen share)
- Connection quality indicator
- Responsive design with CSS

✅ **Documentation**
- PHASE4-CALLS.md - Complete technical documentation
- API endpoint specifications
- WebSocket event documentation
- TURN server setup guide (Coturn)
- Testing checklist
- Troubleshooting guide

## Files Created

### Backend
- `src/backend/database/migrations/004_voice_video_calls.sql`
- `supabase/migrations/20260110140000_voice_video_calls.sql`
- `src/backend/services/callService.js`
- `src/backend/routes/callRoutes.js`

### Backend Updated
- `src/backend/services/socketService.js` - Added call signaling handlers
- `src/backend/server.js` - Registered call routes

### Frontend
- `src/frontend/utils/webrtc.js`
- `src/frontend/components/Call/index.jsx`
- `src/frontend/components/Call/Call.css`

### Documentation
- `PHASE4-CALLS.md`
- `.env.example` - Updated with TURN config

## Quick Start

### 1. Run Database Migration

Apply the Supabase migration:

```bash
# Using Supabase CLI
supabase db push

# Or apply SQL manually in Supabase Dashboard
# File: supabase/migrations/20260110140000_voice_video_calls.sql
```

### 2. Configure Environment

Add to `.env`:

```env
# TURN Server Configuration
TURN_SERVER_HOST=turn.example.com
TURN_SERVER_PORT=3478
TURN_SECRET=your-turn-secret-key
TURN_TTL=86400
```

For local development, you can skip TURN and use public STUN servers (already configured in webrtc.js).

### 3. Use Call Component

```jsx
import Call from './components/Call';

function Chat() {
  const [inCall, setInCall] = useState(false);
  
  return (
    <>
      <button onClick={() => setInCall(true)}>
        Start Call
      </button>
      
      {inCall && (
        <Call
          socket={socket}
          conversationId={conversationId}
          participants={participants}
          onCallEnd={() => setInCall(false)}
        />
      )}
    </>
  );
}
```

## Testing Without TURN Server

For development and testing behind the same network:

1. **Use Public STUN servers** (already configured)
   - stun:stun.l.google.com:19302
   - stun:stun1.l.google.com:19302

2. **Test locally** - Both users on same network work fine with STUN only

3. **Behind NAT/Firewall** - You'll need a TURN server for production

## Architecture

```
User A (Browser)                    User B (Browser)
     |                                   |
     |--- HTTP: Initiate Call --------->|
     |<-- Socket: call:incoming --------|
     |                                   |
     |--- Socket: call:offer ---------->|
     |<-- Socket: call:answer -----------|
     |                                   |
     |<-- Socket: call:ice-candidate -->|
     |--- Socket: call:ice-candidate -->|
     |                                   |
     |<======= WebRTC P2P Media =======>|
     |        (Audio/Video Stream)       |
```

## Media Controls API

```javascript
// Toggle audio
webrtcManager.toggleAudio(false); // mute
webrtcManager.toggleAudio(true);  // unmute

// Toggle video
webrtcManager.toggleVideo(false); // camera off
webrtcManager.toggleVideo(true);  // camera on

// Screen sharing
await webrtcManager.startScreenShare();
webrtcManager.stopScreenShare();

// Get connection stats
const stats = await webrtcManager.getConnectionStats(userId);
console.log('RTT:', stats.connection.roundTripTime);
console.log('Bitrate:', stats.connection.availableOutgoingBitrate);
```

## Supported Call Types

- **Audio Call**: Voice only, ~32-64 kbps per user
- **Video Call**: Audio + video, ~500kbps-2Mbps per user
- **Screen Share**: Replace camera with screen capture

## Browser Support

- ✅ Chrome/Edge (Chromium) - Best support
- ✅ Firefox - Full support
- ✅ Safari - iOS 14.3+ required for WebRTC
- ❌ IE11 - Not supported (WebRTC required)

## Next Steps

1. **Apply Supabase migration** for database schema
2. **Test 1-on-1 calls** with audio and video
3. **Configure TURN server** for production (optional for local dev)
4. **Implement Mediasoup SFU** for efficient group calls (future)
5. **Add call history UI** to display past calls

## Known Limitations

- Group calls use mesh topology (all participants connect to each other)
  - Works well for 2-5 participants
  - Bandwidth intensive for 6+ participants
  - Mediasoup SFU implementation planned for better group call performance
- Call recording infrastructure in place but not implemented
- No call transfer or hold features yet

## Production Checklist

- [ ] Set up TURN server (Coturn)
- [ ] Configure firewall rules for TURN
- [ ] Set TURN_SECRET environment variable
- [ ] Test calls across different networks
- [ ] Monitor bandwidth usage
- [ ] Set up call quality alerts
- [ ] Implement call analytics dashboard
- [ ] Add error tracking (Sentry, etc.)

## Troubleshooting

**No audio/video**: Check browser permissions for camera/microphone

**Connection fails**: 
- Verify both users are online
- Check Socket.io connection
- Test with public STUN servers first

**Poor quality**:
- Monitor connection quality indicator
- Check network bandwidth
- Reduce video resolution
- Switch to audio-only

**Echo/Feedback**:
- Use headphones
- Ensure echo cancellation is enabled
- Check for multiple audio sources

## Support Resources

- Full documentation: `PHASE4-CALLS.md`
- WebRTC docs: https://webrtc.org
- Coturn setup: https://github.com/coturn/coturn
- Mediasoup: https://mediasoup.org

---

**Phase 4 Complete!** Ready for testing and integration.