Real-Time Backend System

Chat + Notification
Engine

Production-grade messaging backend built on Node.js, Socket.io & MongoDB.

Features server-side debouncing, smart notification batching, E2E encryption, offline queuing, change streams, and cursor-based pagination.

19 Source Files
3 Debounce Modes
5 MongoDB Models
24 API Endpoints
💬
Alex & 4 others
5 new messages — Backend Team
🚀
Backend Team
4 members online
🔍
📌
⚙️
A
Debounce engine is live 🔥 The typing indicators now only emit 2 events per session!
Alex • 10:42 AM
🔥 3
👍 1
Y
Notifications are batching perfectly — 30s window before digest delivery
You • 10:43 AM ✓✓
S
MongoDB Change Streams are watching — room stats auto-update on every message!
Sam • 10:44 AM
Y
Offline queue too — reconnect and get all missed messages instantly 🎯
You • 10:44 AM ✓✓
A
Project Layout

Full Folder
Structure

Every file has a single responsibility. The architecture separates transport, business logic, data, and infrastructure layers cleanly.

chat-engine/
📦 package.jsondeps
🔒 .env.example
📖 README.md

📁 src/
⚡ server.jsentry

📁 config/
🗄️ database.js
⚡ redis.js

📁 middleware/
🔐 auth.jsJWT
🚦 rateLimiter.js
⚠️ errorHandler.js

📁 models/
🧬 index.js5 schemas

📁 services/
📁 debounce/
⚡ DebounceEngine.js★ core
📁 notification/
🔔 NotificationService.js★ core

📁 controllers/
👤 authController.js
💬 messageController.js
🏠 roomController.js

📁 routes/
🛣️ index.js

📁 sockets/
🔌 socketHandler.js★ core

📁 workers/
👁️ changeStreamWatcher.js

📁 utils/
📝 logger.js
⚡
DebounceEngine.js
The star of the show. Generic debounce with leading/trailing edge, maxWait ceiling, per-key stats, flush & cancel. TypingDebouncer and NotificationDebouncer built on top.
🔌
socketHandler.js
All Socket.io events: message:send, reactions, typing, read receipts, presence, room joins, offline delivery on reconnect.
🔔
NotificationService.js
Full lifecycle: MongoDB persist → debounce batch → Socket.io delivery → Bull queue for push/email → offline queue for disconnected users.
🧬
models/index.js
5 Mongoose schemas: User (with notification prefs), Room (DM/group/channel), Message (reactions, threads, E2E), Notification (TTL 30d), OfflineQueue.
👁️
changeStreamWatcher.js
MongoDB Change Streams reactor that fans out DB changes to sockets and debounces room stats aggregation — no polling needed.
🛣️
routes/index.js
24 REST endpoints across Auth, Rooms, Messages, and Notifications — all with express-validator, tiered rate limiters, and JWT guard.
System Capabilities

High-Level
Features

Every module is built for production — not just a demo. These features plug together as a cohesive system.

⚡
Server-Side Debouncing
3-mode engine: leading edge (immediate), trailing edge (after silence), and maxWait ceiling. Per-key timer maps with flush/cancel. Prevents MongoDB write storms.
★ Core Feature
💬
Real-Time Messaging
Socket.io with connection state recovery, per-user rooms, message delivery receipts, reactions, threading, and soft deletes. Cursor-based pagination for history.
Socket.io
🔔
Smart Notification Batching
20 events in 30s → 1 digest. Per-user debounce window (configurable). MaxWait ceiling ensures delivery. Quiet hours, muted rooms, per-device targeting.
Debounced
⌨️
Typing Indicators
Leading-edge broadcast (instant) + trailing-edge stop (1.5s silence). No matter how many keystrokes — only 2 socket events per typing session per user.
Socket.io
📴
Offline Message Queue
Missed messages stored in MongoDB with 7-day TTL. On reconnect: force-flush debounced notifications + deliver queued messages instantly via socket.
MongoDB
👁️
Change Streams
MongoDB Change Streams react to DB events in real-time — fan-out new messages, invalidate caches, and run debounced stats aggregation. Zero polling.
MongoDB
🔐
JWT Auth + Refresh Rotation
Access tokens (15min) + refresh tokens (7d) with rotation. Up to 5 simultaneous devices per user. Socket handshake auth. Role-based room guards.
Security
📊
Aggregation Pipelines
Room analytics with messages-per-day, top senders, hourly heatmaps. Unread counts via lastRead cursor. All computed server-side with MongoDB aggregation.
MongoDB
🚦
Tiered Rate Limiting
4 separate limiters: auth (10/15min), API (100/15min), messages (60/min), search (30/min). Keyed by userId when authed, IP when not. Exponential backoff on DB reconnect.
Redis
Interactive Demo

See Debouncing
in Action

These demos simulate the exact debounce logic running in the backend. Type fast, click spam — watch the engine suppress and batch.

📱
Client
Socket.io
WS connect
→
🔌
Socket Handler
Auth + rooms
events
→
⚡
Debounce Engine
Suppress / batch
queued
→
📬
Bull Queue
Async workers
write
→
🗄️
MongoDB
Change streams
Live Debounce Simulator
Keystrokes
0
Events Sent
0
Suppressed
0
Start typing above to see events appear here...
📥 Incoming Queue (unbatched)
Click "Fire Notification" to simulate incoming events
5s
Waiting for events...
✓ Batch delivered! (0 notifications)
📤 Delivered Batches
None yet
📖 Read Receipt Events
Scroll through messages to fire read events
💾 Actual DB Writes (debounced)
Read Events
0
DB Writes
0
Saved Writes
0
Without debouncing: every scroll = 1 DB write.
With 1s debounce: many scrolls = 1 DB write.
Savings scale with scroll speed.
No writes yet
REST Interface

API
Endpoints

All routes use express-validator for input sanitization. JWT-protected endpoints require a valid Bearer token.

🔐 Auth (/api/auth)
POST/registerCreate account
POST/loginGet tokens
POST/logoutRevoke refresh token
POST/refreshRotate access token
GET/meCurrent user
PATCH/me/notificationsUpdate prefs

🏠 Rooms (/api/rooms)
POST/Create DM/group/channel
GET/User's rooms list
GET/:idRoom + members
POST/:id/membersAdd members
DEL/:id/leaveLeave room
PATCH/:id/muteMute/unmute
POST/:id/pin/:msgIdPin message
💬 Messages (/api/rooms/:id/messages)
GET/Cursor pagination
GET/search?q=Full-text search
GET/unreadUnread counts
GET/analyticsRoom heatmap + stats
DEL/:msgIdSoft delete

🔔 Notifications (/api/notifications)
GET/Paginated list
PATCH/read-allMark all read
PATCH/:id/readMark one read

🔌 Socket Events (bidirectional)
EMITmessage:sendSend message
EMITtyping:startTyping debouncer
ONnotificationBatched digest
ONoffline_messagesReconnect flush
Technology

Stack

Each technology is chosen for a specific job. No unnecessary dependencies.

🟢
Node.js 20+
Runtime · ESM modules
🚂
Express.js
HTTP framework
🔌
Socket.io 4
WebSocket · State recovery
🍃
MongoDB + Mongoose
Primary DB · Change Streams
⚡
Redis + BullMQ
Queue · Cache · Pub/sub
🔐
JWT + Bcrypt
Auth · Token rotation
🛡️
Helmet + CORS
HTTP security headers
📝
Winston
Logger · Daily rotate