NestJS Real-time WebSocket Server

A powerful, highly scalable real-time WebSocket server built with NestJS and Socket.IO. This system handles generic event broadcasting alongside a dedicated, in-memory human tracking engine designed to track active users' geolocation coordinates.

Features 🚀

• Real-time Geofencing & Human Tracking Module
  • Instant location tracking via locationUpdate events.
  • O(1) in-memory state tracking to safely map coordinates and dispatch updates globally.
  • Smart disconnect handling that instantly broadcasts missing/disconnected clients to everyone else to avoid ghost nodes.
  • Connect-time snapshots giving new users the exact location of all active trackers upon entry.
• Custom Socket Utilities
  • Includes a custom-built @Ack() parameter decorator to easily latch onto underlying trailing ACK callbacks provided natively by Socket.IO.
• Global CORS Configured
  • Easily accepts cross-origin multi-client access, fully supporting localhost origins alongside Ngrok dev-tunnels testing.

Project Architecture 🏗

The server is built using standard NestJS modular architecture, ensuring separation of concerns:

• AppModule: Core root module mapping dependencies.
• ChatModule / ChatGateway: A lightweight gateway for sending string-based messages and testing custom parameter decorators.
• TrackingModule:
  • TrackingGateway: Listens for location payloads, broadcasts changes to peers, and cleans up sockets when they vanish.
  • TrackingService: In-memory Map-driven repository enforcing logic to assign Socket IDs exclusively to exact user IDs, preventing memory leaks when sockets crash.

Getting Started ⚙️

1. Installation

# Install all required dependencies
$ npm install

2. Running the application

# development
$ npm run start

# watch mode (highly recommended for live reloads)
$ npm run start:dev

# production mode
$ npm run start:prod

3. Testing the App

Once running, the application natively exposes Socket.IO on port 3000. You can connect using any Socket.IO client (like Postman or a React frontend).

WebSocket Events Matrix 📡

Namespace: / (Default)

Event Name	Direction	Payload Example	Description
initialLocations	Server → Client	[{ userId: "u1", lat: 34.0, lng: -118.0, ... }]	Fired when a client successfully connects. Returns an array of everyone's last known locations.
locationUpdate	Client → Server	{ "userId": "uuid", "lat": 12.3, "lng": 45.6, "timestamp": 16000 }	Used to report the client's current coordinates.
locationBroadcast	Server → Client	{ "userId": "uuid", "lat": 12.3, "lng": 45.6, "timestamp": 16000 }	Server echoes the locationUpdate coordinates back to all connected listeners.
userDisconnected	Server → Client	{ "userId": "uuid" }	Alerts the frontend that a user socket dropped, useful for removing map pins.
events	Client ↔ Server	"broadcasting..."	Basic playground event found in ChatGateway using standard emit architectures.

Deployment 🌍

Ensure the platform you use supports HTTP Upgrades (WebSockets) natively. Recommended easy platforms include:

• Railway
• Render
• DigitalOcean App Platform
• Fly.io