Real-Time Engine

Socket.IO & WebRTC Architecture

Comprehensive reference of the event-driven communication layer: matchmaking queues, WebRTC peer signaling, interactive in-call gifting, and session lifecycles.

🔄 Real-Time Matchmaking Lifecycle

Connect & Register register_user

→

Join Queue join_queue

→

Match Discovery match_found

→

WebRTC Signaling signal (SDP/ICE)

→

Live Session chat, gifts, likes

📡 Client & Server Event Reference

register_user Client → Server

Trigger: Immediately upon establishing WebSocket connection. Binds socket ID to authenticated user ID.

Payload:

"usr_65f8a92b0c1e4d7a" // userId string

join_queue Client → Server

Trigger: User taps "Start Matching" on mobile app radar screen or web platform.

Payload:

{
  "userId": "usr_65f8a92b0c1e4d7a",
  "gender": "female",    // 'male' | 'female' | 'both'
  "country": "US",       // ISO country code or empty for global
  "superMatch": false    // Priority matching queue
}

match_found Server → Client

Trigger: The matchmaking engine finds two compatible peers in queue (or connects to an active demo companion).

Payload:

{
  "initiator": true,     // true: create WebRTC SDP offer; false: await offer
  "partner": {
    "id": "usr_912384",
    "name": "Sarah Connor",
    "avatar": "/images/users/sarah.jpg",
    "country": "US",
    "age": 24,
    "gender": "female"
  },
  "partnerSocketId": "soc_abc123xyz",
  "isDemo": false
}

signal Bidirectional Relay

Trigger: PeerJS or WebRTC RTCPeerConnection emits an SDP Offer, SDP Answer, or ICE Candidate. The server relays the payload directly to the partner's socket without storing media.

Client → Server Payload:

{
  "to": "soc_partner_socket_id",
  "signal": {
    "type": "offer",     // 'offer' | 'answer' | 'candidate'
    "sdp": "v=0\r\no=- 123456 ...",
    "candidate": { ... }
  }
}

Server → Partner Payload:

{
  "from": "soc_sender_socket_id",
  "signal": { ... }
}

send_message / receive_message Bidirectional Relay

Trigger: User types an in-call text message, clicks a reaction heart, or sends an animated diamond gift during an active video session.

Client → Server (send_message):

{
  "to": "soc_partner_socket_id",
  "message": "Hey there! Nice to meet you 😊",
  "isGift": false,
  "giftId": null
}

Server → Partner (receive_message):

{
  "from": "soc_sender_socket_id",
  "message": "Hey there! Nice to meet you 😊",
  "isGift": false,
  "giftId": null,
  "timestamp": 1726693200000
}

skip_match / partner_skipped Session Control

Trigger: User taps the "Next" or "Skip" button. Closes active peer stream, records session duration into call history, and immediately notifies partner.

Client → Server: socket.emit('skip_match')
Server → Partner: partner_skipped (causes client to automatically display reconnection animation and re-enter queue).

online_users_count Server → Broadcast

Trigger: Emitted automatically every 5 seconds to all connected sockets to update the live counter badge on web and mobile home screens.

Payload:

1482 // Active connections + configured fake online users