General Socket Service

Overview

The General Socket Service is a real-time WebSocket communication service running on port 4000. It provides bi-directional event-based communication between the DashClicks platform and connected clients using Socket.IO. The service manages four distinct namespaces for different features: conversations, live chat, lead tracking, and shared events.

Key Responsibilities:

• Real-time messaging and conversation management
• Prospect communication tracking
• Lead finder notifications
• General platform event broadcasting
• User presence and active status tracking
• Multi-instance horizontal scaling via Redis

---

Architecture

Service Structure

general-socket/
├── index.js                    # Express + Socket.IO server entry
├── import.js                   # Module import utility
├── package.json
├── Dockerfile
├── Middleware/
│   ├── is-auth.js             # JWT authentication for users
│   ├── is-auth-visitor.js     # Visitor authentication
│   └── scope.js               # Permission scope verification
├── Integrations/
│   ├── index.js               # Integration loader
│   ├── Conversation/          # Team conversation events
│   ├── Prospect/              # Prospect communication events
│   ├── LeadFinder/            # Lead tracking events
│   ├── Shared/                # General platform events
│   ├── RestAPI/               # HTTP endpoints for emitting events
│   └── Utils/
│       └── counter.js         # Conversation counter provider
└── Utils/
    ├── socket.js              # Socket.IO configuration singleton
    └── fcm.js                 # Firebase Cloud Messaging utility

Socket.IO Namespaces

The service implements 4 distinct namespaces:

Namespace	Path	Purpose	Authentication
Conversation	/v1/conversation	Team internal messaging	Required (JWT + scope: conversation)
LiveChat	/v1/conversation/live	Same as Conversation	Required (JWT + scope: conversation)
LeadFinder	/v1/lead-finder	Lead scraper tracking	None
Shared	/v1/shared	General platform events	Required (JWT + scope: conversation)

---

Documentation Structure

This documentation is organized into the following sections:

• Server Configuration (documentation unavailable) - Express server, Socket.IO setup, Redis adapter
• Authentication - JWT authentication, token sources, scope verification
• Conversation Integration - Team messaging events and flows
• Prospect Integration - Prospect communication tracking
• LeadFinder Integration - Lead scraper connection management
• Shared Integration - General platform events
• REST API - HTTP endpoints for triggering socket emissions
• Data Flows - Message flows, prospect flows, scraper flows
• Deployment - Environment variables, Docker, monitoring

---

Quick Start

Connection Example

import io from 'socket.io-client';

const socket = io('http://localhost:4000/v1/conversation', {
  transports: ['websocket'],
  query: { token: 'your_jwt_token' },
});

socket.emit('join', {}, response => {
  console.log('Connected:', response);
});

socket.on('message', data => {
  console.log('New message:', data);
});

REST API Example

# Emit event to specific user
POST http://localhost:4000/emit/64abc123def/notification
Content-Type: application/json

{
  "title": "New Lead",
  "message": "You have a new lead!"
}

---

Key Features

Real-Time Communication

• Bi-directional Events: Client-server event exchange
• Multiple Namespaces: Isolated communication channels
• Presence Tracking: User online/offline status
• Typing Indicators: Real-time typing notifications

Scalability

• Redis Adapter: Horizontal scaling with pub/sub
• Connection Pooling: Efficient database connections
• Event Batching: Optimized emission patterns
• Graceful Shutdown: Clean connection closure

Security

• JWT Authentication: Token-based user verification
• Scope Verification: Permission-based access control
• CORS Support: Cross-origin request handling
• Secure WebSockets: WSS in production

---

Related Services

• Conversation Socket (Port 6001) - Deprecated messaging service
• Internal API (Port 5002) - Database operations for conversations
• External API (Port 5003) - Webhook handlers (Twilio, SendGrid)
• Notification Service (Port 5008) - Push notifications

---

Support & Resources

• Source Code: general-socket/
• Models: general-socket/models/ (copied from shared/models/)
• Utilities: general-socket/utilities/ (copied from shared/utilities/)

Note: Never edit models/ or utilities/ folders directly in the service directory. Always edit in /shared/ and run npm run copySharedFiles.