TalkBox is an open-source, real-time chat application that combines a Node.js/Express REST API with a Socket.IO WebSocket layer and a React/Vite frontend. It was designed as a complete, production-shaped reference for developers who want to understand how JWT-authenticated REST endpoints and persistent WebSocket connections work together inside a single MERN project.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/abdelhafid37/talkbox/llms.txt
Use this file to discover all available pages before exploring further.
What TalkBox Does
At its core, TalkBox lets any number of registered users find each other, open a private conversation, and exchange messages that are delivered instantly without a page refresh. Every session is secured with JSON Web Tokens: the same token that guards REST routes is also verified by the Socket.IO middleware before a WebSocket connection is accepted, so there is a single, consistent identity layer across both communication channels.Key Capabilities
Real-Time Messaging
Messages are sent and delivered over a persistent Socket.IO connection. Both the sender and receiver receive the
newMessage event the moment it is emitted — no polling required.JWT Authentication
Registration and login are handled through REST endpoints. The resulting JWT is attached to every subsequent API call and to the Socket.IO handshake, keeping both transports secure.
Online Presence
When a user connects and emits the
join event, their ID is added to an in-memory map. All connected clients receive an updated onlineUsers list in real time whenever someone joins or disconnects.Conversation History
Past messages are persisted in MongoDB and fetched over REST when a conversation is opened, so users always see their full message history alongside live incoming messages.
Responsive Interface
The React frontend is built with Tailwind CSS and adapts cleanly to both desktop and mobile viewports, with automatic scrolling to the latest message and loading state indicators.
Protected Routes
A
ProtectedRoute component in React wraps authenticated pages. Unauthenticated visitors are redirected to the login page; valid sessions are hydrated from context via AuthProvider.Tech Stack
TalkBox is assembled from focused, well-supported libraries across the full stack. Backend — Node.js / Express| Package | Version | Role |
|---|---|---|
express | ^5.2.1 | HTTP server and REST routing |
mongoose | ^9.7.4 | MongoDB object modelling |
socket.io | ^4.8.3 | WebSocket server |
jsonwebtoken | ^9.0.3 | JWT issuance and verification |
bcrypt | ^6.0.0 | Password hashing |
cors | ^2.8.6 | Cross-origin request handling |
dotenv | ^17.4.2 | Environment variable loading |
nodemon | ^3.1.14 | Auto-restart during development |
| Package | Version | Role |
|---|---|---|
react | ^19.2.7 | UI rendering |
vite | ^8.1.1 | Development server and bundler |
react-router-dom | ^7.18.1 | Client-side routing |
socket.io-client | ^4.8.3 | WebSocket client |
axios | ^1.18.1 | HTTP requests to the REST API |
tailwindcss | ^4.3.3 | Utility-first styling |
date-fns | ^4.4.0 | Timestamp formatting |
Architecture Overview
TalkBox separates its communication into two distinct channels that share the same authentication layer. REST API — persistent data and identity The Express application mounts three route groups:/api/auth— registration and login, returns a JWT on success/api/users— look up other registered users to start a conversation/api/messages— fetch the history of a conversation between two users
/api/auth is protected by an authMiddleware that verifies the JWT from the Authorization header.
WebSocket — real-time events
initializeSocket attaches a Socket.IO Server instance to the same underlying HTTP server. An io.use middleware verifies the JWT passed in socket.handshake.auth.token before allowing any connection. Once authenticated, the server handles three events:
join— registers the socket in anonlineUsersmap and broadcasts the updated listsendMessage— persists the message to MongoDB, then emitsnewMessageto both sender and receiver socketsdisconnect— removes the socket fromonlineUsersand re-broadcasts the list
Explore Further
Quickstart
Run the server and client locally in under five minutes with step-by-step setup instructions.
API Reference
Detailed documentation for every REST endpoint: request shapes, response schemas, and auth requirements.
Architecture
A deeper look at how the REST and WebSocket layers interact, the MongoDB data models, and the auth flow.
Features
Full breakdown of online presence, conversation history, message delivery, and the responsive UI.