ChatRoom

Real-Time Event Counter & Multi-Room Chat Application built with WebSockets Node.js | WebSocket API | Full-Duplex | Docker

A hands-on reference project designed to learn core WebSocket mechanics: persistent connections, full-duplex bi-directional streaming, room-based broadcasting, and connection state management.

Overview

ChatRoom demonstrates how WebSockets eliminate HTTP polling overhead by establishing a single long-lived TCP connection. Clients can join isolated room channels, exchange live chat messages, and trigger real-time counter updates synchronized across all peers in the room instantly.

Project Directory Structure

The layout of the project files and their key responsibilities:

ChatRoom/
├── package.json      # Project metadata, dependencies (express, ws), and scripts
├── Dockerfile        # Container configuration for the Node.js application
├── server.js         # HTTP server, WebSocket handshake, room manager & broadcaster
└── public/
    ├── index.html    # UI layout for chat streams, rooms list, and counter button
    └── app.js        # Client-side WebSocket client (new WebSocket, handlers, DOM update)

Core Architecture & Technical Mechanics

• HTTP Upgrade Handshake: Understand how TCP socket connections are initialized over HTTP ports.
• Room Channel Isolation: Learn selective event targeting vs global server broadcasting.
• Bidirectional Streaming: Handle client actions (publish) and server state sync (push) asynchronously.
• Presence & Heartbeats: Manage lifecycle states (connect, reconnect, close) cleanly.

Event Schema Specification

1. Client -> Server Events

Join Room:

{
  "type": "JOIN_ROOM",
  "payload": { "room": "general", "username": "Hamid" }
}

Send Chat Message:

{
  "type": "SEND_MESSAGE",
  "payload": { "text": "Hello WebSockets!" }
}

2. Server -> Client Broadcasts

Broadcast Message / Counter Update:

{
  "type": "COUNTER_UPDATED",
  "payload": { "count": 42, "updatedBy": "Hamid" }
}

Quick Start & Setup (Docker)

No local Node.js installation is required.

1. Build the Docker Image:

   docker build -t chatroom-app .

2. Run the Container:

   docker run -p 3000:3000 chatroom-app

3. Access the Application: Open http://localhost:3000 in multiple browser tabs to test real-time multi-client syncing.