Chapter 12 — Project P4 — Chat Backend

Why this project

Real-time communication is table stakes for modern applications — support chat, live collaboration, multiplayer games, notification systems. This project strips WebSockets down to their engineering fundamentals: connection management, presence tracking, message persistence, and horizontal scaling. You'll build a chat backend that works with one server and scales to many, using Redis pub/sub to bridge messages across instances.

Spec — what we're building

WebSocket Protocol

Client → Server messages:
  { type: "join", roomId: "room_123" }
  { type: "leave", roomId: "room_123" }
  { type: "message", roomId: "room_123", content: "Hello!" }
  { type: "typing:start", roomId: "room_123" }
  { type: "typing:stop", roomId: "room_123" }
 
Server → Client messages:
  { type: "message", id: "msg_456", roomId: "room_123", userId: "user_1",
    username: "alice", content: "Hello!", createdAt: "..." }
  { type: "presence", roomId: "room_123", users: ["user_1", "user_2"] }
  { type: "typing", roomId: "room_123", userId: "user_2", isTyping: true }
  { type: "error", code: "ROOM_NOT_FOUND", message: "Room does not exist" }
  { type: "history", roomId: "room_123", messages: [...] }

Data Models

-- Users (shared from auth module)
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- Chat rooms
CREATE TABLE rooms (
  id UUID PRIMARY KEY DEFAULT

Typing indicators and presence are ephemeral — Redis only, not persisted to PostgreSQL.

Architecture Decision Records

ADR-1: ws (not Socket.io) for WebSocket server. Socket.io adds auto-reconnection, fallback transports, and rooms abstraction — valuable but obscures the fundamentals. Using the ws library forces you to understand the WebSocket protocol directly.

ADR-2: Redis pub/sub for cross-server broadcasting. When running multiple server instances, a message sent to Server A must reach clients connected to Server B. Redis pub/sub channels per room broadcast messages across all server instances.

ADR-3: PostgreSQL for message persistence, Redis for ephemeral state. Messages are durable (PostgreSQL). Presence and typing indicators are ephemeral (Redis with TTL). This separation optimizes each store for its access pattern.

ADR-4: No authentication in WebSocket handshake headers — use query param token. The WebSocket upgrade request doesn't support custom headers in browsers. Pass the JWT as a query parameter: ws://localhost:3000?token=.... Validate on connection.

Project layout

chat-backend/
├── src/
│   ├── config/
│   │   └── index.ts              # Env vars, Redis URL, DB pool, JWT secret
│   ├── db/
│   │   ├── migrations/
│   │   │   ├── 001_users.sql
│   │   │   ├── 002_rooms.sql
│   │   │   ├── 003_room_members.sql
│   │   │   └── 004_messages.sql
│   │   ├── pool.ts
│   │   └── migrate.ts
│   ├── ws/
│   │   ├── server.ts             # WebSocket server setup + upgrade handling
│   │   ├── connection-manager.ts # Track connected clients per user, per room
│   │   ├── handlers/
│   │   │   ├── auth.ts           # JWT validation on connect
│   │   │   ├── join.ts           # Join room handler
│   │   │   ├── message.ts        # Message handler (persist + broadcast)
│   │   │   ├── typing.ts         # Typing indicator handler
│   │   │   └── presence.ts       # Presence broadcast handler
│   │   └── types.ts              # WebSocket message types
│   ├── redis/
│   │   ├── pubsub.ts             # Redis publisher + subscriber
│   │   └── presence.ts           # Presence tracking (Redis sets)
│   ├── rest/
│   │   ├── rooms.routes.ts       # REST endpoints for room CRUD
│   │   └── messages.routes.ts    # REST endpoint for message history
│   ├── middleware/
│   │   ├── auth.ts               # JWT middleware (shared with WS)
│   │   └── error-handler.ts
│   ├── lib/
│   │   ├── errors.ts
│   │   └── logger.ts
│   └── app.ts                    # Express + WS server

Implementation checklist

Phase 1: Foundation (Day 1-2)

• Initialize project with TypeScript, Express, ws, pg, ioredis
• Set up PostgreSQL + Redis with Docker Compose
• Write and run migrations (users, rooms, room_members, messages)
• Implement JWT auth for REST endpoints
• Implement REST endpoints: POST /api/rooms, GET /api/rooms, POST /api/rooms/:id/join
• Implement GET /api/rooms/:id/messages — cursor-paginated message history

Phase 2: WebSocket Core (Day 3-4)

• Set up ws WebSocket server alongside Express
• Implement JWT validation on WebSocket upgrade (query param token)
• Build ConnectionManager: Map of userId → Set of WebSocket connections
• Implement join handler: validate room membership, add to room, send history
• Implement leave handler: remove from room tracking
• Implement message handler: persist to PG, broadcast to room
• Test with wscat or a simple HTML client

Phase 3: Presence & Typing (Day 5)

• Implement presence tracking: Redis Set room:{roomId}:presence with TTL
• Broadcast presence updates when users join/leave
• Implement heartbeat: client sends ping every 30s; server tracks last heartbeat
• Implement stale presence cleanup: remove users with >60s since last heartbeat
• Implement typing indicators: typing:start/typing:stop broadcast via Redis pub/sub (not persisted)

Phase 4: Horizontal Scaling (Day 6-7)

• Set up Redis pub/sub: each server subscribes to room:{roomId} channel
• On message: publish to Redis channel AND broadcast to local clients
• On Redis message received: broadcast to local clients connected to that room
• Test with docker-compose running 2 app instances behind nginx
• Verify: Client A (connected to Server 1) can chat with Client B (connected to Server 2)

Phase 5: Hardening (Day 8)

• Connection rate limiting (prevent WebSocket DoS)
• Message size limits (max 10KB per message)
• Message rate limiting per user (max 5 messages/second)
• Graceful shutdown: close connections cleanly, broadcast "user offline"
• Reconnection handling: client-side reconnection with exponential backoff
• Structured logging with correlation IDs across WS connections

Key implementation details

1. Connection Manager

The connection manager tracks which users are connected and which rooms they're in:

// ws/connection-manager.ts
import WebSocket from 'ws';
 
interface ClientInfo {
  userId: string;
  username: string;
  ws: WebSocket;
  rooms: Set<string>;

2. WebSocket server with auth

// ws/server.ts
import { WebSocketServer, WebSocket } from 'ws';
import { Server } from 'http';
import jwt from 'jsonwebtoken';
import { connectionManager } from './connection-manager'

3. Cross-server broadcasting with Redis pub/sub

// redis/pubsub.ts
import Redis from 'ioredis';
import { connectionManager } from '../ws/connection-manager';
 
const publisher = new Redis({ host: 'localhost', port: 6379 });
const

4. Message handler (persist + broadcast)

// ws/handlers/message.ts
import { db } from '../../db/pool';
import { broadcastMessage } from '../../redis/pubsub';
 
export async function handleMessage(
  userId: string,
  username: string,
  roomId

Common mistakes

Interview questions

1. Q: Why use Redis pub/sub instead of having each server track all connected clients? A: Each server only knows about clients connected to it. If Server A has Client 1 and Server B has Client 2 in the same room, Server A can't directly send a message to Client 2. Redis pub/sub bridges this gap: Server A publishes to Redis, Server B (subscribed) receives and broadcasts to Client 2. This is the standard pattern for horizontally scaling WebSocket servers.

2. Q: Why persist messages to PostgreSQL instead of keeping them in Redis? A: Redis is primarily an in-memory store. While it can persist to disk (RDB/AOF), it's not designed as a durable message store. Redis restarts can lose data. PostgreSQL provides ACID durability, indexing for efficient pagination of message history, and is the system you already have operational expertise for. Use Redis for what it's good at (ephemeral pub/sub, presence); use PostgreSQL for what it's good at (durable storage, querying).

3. Q: How do you handle the case where a message is broadcast but the recipient is offline? A: The message is persisted to PostgreSQL regardless. When the recipient reconnects and joins the room, they receive a history event with recent messages (last 50). The real-time broadcast is best-effort delivery; PostgreSQL is the source of truth. This is the same pattern Slack uses: messages are always in the database; the WebSocket is for live delivery.

Summary

This project builds a production-grade chat backend with WebSockets, PostgreSQL, and Redis. The connection manager tracks clients and rooms. Messages are persisted to PostgreSQL for durability and broadcast via WebSocket for real-time delivery. Redis pub/sub enables horizontal scaling across multiple server instances. Presence tracking uses Redis Sets with TTLs; typing indicators use ephemeral pub/sub messages. The architecture separates concerns cleanly: PostgreSQL for durable state, Redis for ephemeral coordination, WebSockets for real-time transport.

Quick recall

• ws library (not Socket.io) for understanding the raw WebSocket protocol.
• Connection Manager: Map of userId → .
• Redis pub/sub per room for cross-server message broadcasting.
• Messages: persist to PostgreSQL FIRST, then broadcast via WebSocket + Redis.
• Presence: Redis Set room:{roomId}:presence with heartbeat-based TTL.
• Heartbeat: server pings every 30s; no pong = connection terminated.
• Client reconnection: exponential backoff (1s → 2s → 4s → 8s → max 30s).
• On reconnect: send message history (last 50) so the client catches up.
• JWT passed as query parameter in WebSocket URL (browsers don't support custom headers on upgrade).