god_eye/.github/copilot-instructions.md

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

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.