# GodEye Signal Center - AI Coding Instructions

## System Architecture

This is a **WebRTC-based remote camera access system** with three core components:
- **Backend Server** (Node.js + Socket.IO): Signaling center at `/backend/src/`
- **Android Client** (Kotlin): Camera provider at `/android-client/src/`  
- **Web Demo** (HTML/JS): Testing interface at `/backend/public/`

**Key Data Flow**: `Android <--WebSocket--> Backend <--WebSocket--> Operator`

## Critical Components

### SessionManager (`/backend/src/managers/SessionManager.js`)
- Manages camera access sessions with UUID tracking
- Maps: `deviceId -> sessions[]` and `operatorId -> sessions[]`
- Session lifecycle: create → active → ended with detailed state tracking

### DeviceManager (`/backend/src/managers/DeviceManager.js`) 
- Maintains registry of Android devices and desktop operators
- Device capabilities: `["back", "front", "wide", "telephoto"]` camera types
- Real-time connection status with heartbeat monitoring

### WebSocket Protocol (`/backend/src/server.js`)
**Android Registration**: `register:android` → `register:success`
**Camera Requests**: `camera:request` → `camera:response` → WebRTC signaling
**WebRTC Flow**: `webrtc:offer` ↔ `webrtc:answer` ↔ `webrtc:ice-candidate`

## Developer Workflows

### Backend Development
```bash
cd backend/
node src/server.js  # Runs on port 3001
# Web demo available at http://localhost:3001
```

### Testing Complete System
1. Start backend server
2. Open web demo (simulates Android + Operator)
3. Test full cycle: device registration → camera request → WebRTC stream

## Project Conventions

### Error Handling Pattern
All socket events have corresponding error events: `camera:error`, `register:error`, `webrtc:error`

### ID Generation
- `deviceId`: Android ANDROID_ID or UUID
- `sessionId`: UUID v4 for each camera session
- `operatorId`: UUID v4 for desktop clients

### Camera Type Constants
Standard types: `"back"`, `"front"`, `"wide"`, `"telephoto"`

## Integration Points

### WebSocket Events (Socket.IO)
- Android: `register:android`, `camera:response`, `camera:disconnected`
- Operators: `register:operator`, `camera:request`, `camera:switch`
- WebRTC: `webrtc:offer/answer/ice-candidate` bidirectional

### REST API (`/api/`)
- `/api/status` - System health and metrics
- `/api/operators/*` - Operator management with auth
- `/api/admin/*` - Administrative functions

**Architecture Decision**: WebSocket for real-time, REST for CRUD operations

When working on this codebase, prioritize understanding the session lifecycle and WebSocket protocol flow before making changes.
