chatrtc/README.md

# 🚀 ChatRTC - Complete Setup Guide

## Project Overview

ChatRTC is a complete Android WebRTC chat application with a Node.js signaling server. Users can join with just a nickname and enjoy:

- 💬 **Text messaging with emoji support**
- 📹 **Video calling with WebRTC**
- 🎤 **Audio calling**
- 👥 **Multi-user chat rooms**
- 📱 **Modern Android UI**

## 📁 Project Structure

```
chatrtc/
├── app/                          # Android Application
│   ├── src/main/java/com/chatrtc/app/
│   │   ├── MainActivity.java     # Nickname entry & permissions
│   │   ├── ChatActivity.java     # Main chat interface
│   │   ├── adapter/
│   │   │   └── ChatAdapter.java  # Chat message RecyclerView adapter
│   │   ├── model/
│   │   │   └── ChatMessage.java  # Message data model
│   │   └── webrtc/
│   │       └── WebRTCManager.java # WebRTC connection management
│   └── src/main/res/             # Android resources (layouts, drawables, etc.)
├── server/                       # Node.js Signaling Server
│   ├── server.js                 # Main server implementation
│   ├── package.json              # Dependencies and scripts
│   ├── start-server.sh           # Easy startup script
│   ├── test-client.js            # Server testing utility
│   └── README.md                 # Server documentation
└── README.md                     # This file
```

## 🛠️ Quick Setup

### 1. Server Setup (5 minutes)

```bash
# Navigate to server directory
cd server

# Install dependencies
npm install

# Start the server
npm start
# or use the convenient script:
./start-server.sh start dev
```

**Server will be running at:**
- 🌐 **Local**: http://localhost:3000
- 📱 **Android Emulator**: http://10.0.2.2:3000
- 🔗 **Network**: http://YOUR_IP:3000

### 2. Android App Setup

1. **Open in Android Studio**: Open the `chatrtc` folder
2. **Update Server URL**: In `WebRTCManager.java`, update:
   ```java
   private static final String SIGNALING_SERVER_URL = "http://10.0.2.2:3000"; // For emulator
   // or "http://YOUR_SERVER_IP:3000" for real device
   ```
3. **Build & Run**: Connect device/emulator and click Run

### 3. Test the App

1. **Grant Permissions**: Allow camera and microphone access
2. **Enter Nickname**: Type any nickname and join
3. **Start Chatting**: Send messages, toggle video/audio
4. **Multi-user**: Run on multiple devices to test P2P connections

## 🎯 Key Features Implemented

### Android App Features
- ✅ **Simple nickname entry** - No registration required
- ✅ **Emoji support** - Full emoji keyboard and rendering
- ✅ **WebRTC video/audio** - Peer-to-peer communication
- ✅ **Modern chat UI** - Material Design with chat bubbles
- ✅ **Media controls** - Toggle video/audio, switch cameras
- ✅ **Permission handling** - Smooth camera/mic permission flow

### Server Features
- ✅ **Real-time signaling** - WebRTC offer/answer/ICE exchange
- ✅ **Room management** - Multiple users in chat rooms
- ✅ **User tracking** - Monitor connections and states
- ✅ **REST API** - Server monitoring and room info
- ✅ **Error handling** - Comprehensive error management
- ✅ **Production ready** - PM2 support, logging, CORS

## 📱 Android Integration Details

### WebRTC Connection Flow
1. User enters nickname → joins default room
2. Server notifies other users → triggers WebRTC offer
3. Peer connection established → direct P2P communication
4. Data channels used for text messages
5. Media streams for audio/video

### Key Android Components
- **MainActivity**: Handles nickname input and permissions
- **ChatActivity**: Main UI with video views and chat list
- **WebRTCManager**: Manages all WebRTC connections and signaling
- **ChatAdapter**: Handles different message types (own/other/system)

## 🖥️ Server API Reference

### REST Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Server status dashboard (HTML) |
| `/api/status` | GET | Server statistics (JSON) |
| `/api/rooms` | GET | List all active rooms |
| `/api/rooms/:id` | GET | Specific room information |
| `/health` | GET | Health check endpoint |

### Socket.IO Events
**Client → Server:**
- `join-room` - Join chat room with nickname
- `offer/answer/ice-candidate` - WebRTC signaling
- `media-state` - Video/audio state updates
- `chat-message` - Text message fallback

**Server → Client:**
- `joined-room` - Successful room join confirmation
- `user-joined/user-left` - User connection notifications
- `offer/answer/ice-candidate` - WebRTC signaling relay
- `user-media-state` - Media state broadcasts

## 🔧 Development & Testing

### Server Commands
```bash
# Development with auto-restart
npm run dev

# Production mode
npm start

# Process manager (recommended for production)
./start-server.sh start pm2

# Test server connectivity
./start-server.sh test

# Show server info
./start-server.sh info
```

### Android Development
```bash
# Build debug APK
./gradlew assembleDebug

# Build using Docker (recommended for consistent environment)
docker run -ti --rm --name gradle -v $PWD:/android-app --workdir /android-app androidsdk/android-31 ./gradlew build

# Install on connected device
adb install app/build/outputs/apk/debug/app-debug.apk

# View app logs
adb logcat | grep ChatRTC
```

### Testing Multi-User Scenarios
1. **Multiple Devices**: Install on different Android devices
2. **Emulator + Device**: Run on emulator and real device
3. **Multiple Emulators**: Create multiple AVDs for testing

## 🚀 Production Deployment

### Server Deployment
```bash
# Using PM2 (recommended)
npm install -g pm2
npm run pm2:start

# Using Docker
docker build -t chatrtc-server .
docker run -p 3000:3000 chatrtc-server

# Manual deployment
NODE_ENV=production npm start
```

### Android Release
```bash
# Generate release APK
./gradlew assembleRelease

# Generate signed APK (configure keystore first)
./gradlew bundleRelease
```

## 🐛 Troubleshooting

### Common Issues

**Server won't start:**
- Check if port 3000 is available: `lsof -i :3000`
- Verify Node.js installation: `node --version`

**Android connection failed:**
- Verify server URL in WebRTCManager.java
- Check network connectivity
- Ensure server is accessible from device network

**WebRTC not working:**
- Grant camera/microphone permissions
- Check for HTTPS requirement in production
- Verify STUN server connectivity

**No video/audio:**
- Test on real device (emulator has limited media support)
- Check device camera/microphone functionality
- Verify WebRTC peer connection establishment

### Debug Commands
```bash
# Check server status
curl http://localhost:3000/api/status

# Monitor server logs
tail -f server/logs/chatrtc-server.log

# Android logs
adb logcat | grep -E "(WebRTC|ChatRTC|WebRTCManager)"
```

## 📊 Performance & Scalability

### Current Limitations
- **P2P only**: Direct connections between 2 users
- **Single server**: One signaling server instance
- **Memory-based storage**: User data not persisted

### Scaling Options
- **MCU/SFU**: Media server for group calls
- **Redis**: Distributed session storage
- **Load balancer**: Multiple server instances
- **Database**: Persistent user/room data

## 🎨 Customization

### UI Customization
- **Colors**: Edit `app/src/main/res/values/colors.xml`
- **Layouts**: Modify XML layouts in `res/layout/`
- **Icons**: Replace drawable resources
- **Themes**: Update `res/values/themes.xml`

### Server Customization
- **Room limits**: Modify server configuration
- **STUN/TURN servers**: Update WebRTC configuration
- **Message limits**: Configure rate limiting
- **Logging**: Adjust log levels and destinations

## 📄 License

MIT License - Feel free to use and modify for your projects!

## 🤝 Contributing

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

## 🆘 Support

- 📝 **Issues**: Create GitHub issues for bugs/features
- 📚 **Documentation**: Check server and app README files
- 🔍 **Debugging**: Enable debug logs for detailed information

---

**🎉 You're all set! Your ChatRTC application is ready for development and deployment.**