# Development Log

## 2025-09-07 - Initial Development Environment Setup

- Starting development environment for WebRTC screen sharing evaluation project
- Project compares P2P vs SFU architectures for screen sharing performance
- Key metrics: CPU utilization, Glass-to-Glass latency, Text Legibility Score
- Dead End: Docker Compose build failed - "rpc error: code = Unavailable desc = error reading from server: EOF"
  - Issue occurred during client build process after ~245 seconds
  - Likely resource constraints or Docker daemon issue during large build
- Success: Colima Docker daemon started successfully
- Success: Local development environment started successfully
  - Signaling server on port 3001 (healthy)
  - SFU server on port 3002 (mock mode, healthy)
  - React client running on port 3000
- Success: Fixed screen sharing connection issues
  - Dead End: WebRTC client connecting to Docker hostname instead of localhost
  - Dead End: Signaling server not handling specific WebRTC events (offer/answer/ice-candidate)
  - Success: Changed signaling URL from 'http://signaling-server:3001' to 'http://localhost:3001'
  - Success: Added specific WebRTC event handlers to signaling server (offer, answer, ice-candidate)
  - Success: Added comprehensive debugging statements throughout WebRTC service and signaling server
  - Result: P2P and SFU screen sharing is now working between presenter and viewers
  - Success: Signaling server WebSocket connections established successfully
  - Success: Session management working properly (preventing multiple presenters per session)
  - Success: Fixed macOS screen sharing permission dialog issue
    - Problem: Browser gets stuck waiting for screen selection after granting permission
    - Root cause: macOS has two-step permission process (browser permission + system screen selection)
    - Solution: Added macOS-specific user instructions and enhanced error handling
    - Added specific error messages for NotAllowedError, AbortError, NotFoundError, NotSupportedError
    - Added track 'ended' event listener to detect when user stops sharing via browser controls
  - Success: Fixed multiple permission dialog issue (4 clicks problem)
    - Root cause: React useEffect dependency cycle causing multiple startSharing calls
    - Issue 1: startSharing callback depended on isSharing state, creating re-render cycle
    - Issue 2: useEffect dependencies included callbacks that changed on every render
    - Solution: Added protection flags (isRequestingPermission, hasInitialized) to prevent multiple calls
    - Solution: Removed isSharing dependency from startSharing callback
    - Solution: Changed useEffect dependencies to only sessionId and role (stable values)
    - Added comprehensive debugging with call numbers and state tracking
  - Success: Fixed cross-device connectivity issue (Mac to iPhone)
    - Problem: iPhone viewers couldn't see Mac presenter's screen
    - Root cause: WebRTC service hardcoded signaling URL to 'http://localhost:3001'
    - Issue: When iPhone accesses Mac's IP (192.168.4.31:3000), it tried connecting to iPhone's localhost:3001
    - Solution: Made signaling URL dynamic using window.location.hostname
    - Implementation: URL now automatically becomes 'http://192.168.4.31:3001' when accessed from iPhone
    - Result: Cross-device screen sharing now works between Mac presenter and iPhone viewer

# Tech Stack

## Frontend

- React 18.x with TypeScript
- WebRTC APIs for P2P connections
- Custom hooks and services for metrics collection

## Backend

- Node.js signaling server with Socket.io
- Mediasoup SFU server for selective forwarding
- Express.js for REST API endpoints

## Testing & Analysis

- Puppeteer for automated browser testing
- Python 3.9+ for data analysis and visualization
- Tesseract.js for OCR-based text legibility scoring

## Infrastructure

- Docker and Docker Compose for orchestration
- Network traffic control (tc qdisc) for simulating conditions

# Architecture Overview

## Directory Structure

- `/client/` - React TypeScript frontend application
- `/signaling-server/` - WebRTC signaling coordination server
- `/sfu-server/` - Mediasoup SFU implementation
- `/test-framework/` - Automated testing with Puppeteer
- `/data-analysis/` - Python-based statistical analysis and visualization
- `/docker/` - Container orchestration files

## Entry Points

- Client: `client/src/index.tsx` - React application entry
- Signaling: `signaling-server/src/server.js` - Express + Socket.io server
- SFU: `sfu-server/src/server.js` - Mediasoup SFU server
- Tests: `test-framework/src/index.js` - Main test suite runner

## Configuration

- Docker Compose: `docker/docker-compose.yml` - Complete system orchestration
- Multiple Dockerfiles for different services
- Environment variables for service coordination

# Module Dependencies

## Component Relationships

- Client connects to signaling server for session coordination
- SFU server coordinates with signaling server for room management
- Test framework controls multiple browser instances via Puppeteer
- Data analysis processes results from test framework output

## Data Flow

- WebRTC signaling flow: Client -> Signaling Server -> SFU Server
- Metrics collection: Client -> Test Framework -> CSV/JSON results
- Analysis pipeline: Raw results -> Python analysis -> Visualization charts

## External Integrations

- WebRTC native browser APIs for media streaming
- Mediasoup for SFU functionality
- Tesseract.js for OCR text analysis
- TC (Traffic Control) for network condition simulation