🚀 Live Demo  ·  📖 API Docs  ·  🐛 Report Bug  ·  ✨ Request Feature

---

📌 Table of Contents

• Overview
• Features
• Tech Stack
• Architecture
• Project Structure
• Getting Started
• Environment Variables
• API Reference
• Socket Events
• Screenshots
• Roadmap
• Deployment
• Author

---

🌟 Overview

ChatApp is a production-ready, full-stack real-time chat application that enables seamless instant messaging between users. Built on a modern JavaScript ecosystem, it demonstrates best practices in:

• ⚡ Real-time WebSocket communication
• 🔐 Secure JWT authentication
• 🏗️ Scalable REST API design
• 🎨 Modern React frontend architecture of website

Whether you're exploring WebSocket-based communication or using this as a foundation for your own project, ChatApp covers the fundamentals with clean, readable, well-structured code.

💡 Key highlight: Every message is delivered instantly via Socket.io — no polling, no delays, no refresh needed in Chats.

---

✨ Features

🔐 Authentication & Security User registration & login flows JWT-based session management Protected routes on client & server Passwords hashed with JWT authentication. bcrypt 💬 Real-Time Messaging Instant delivery via WebSockets Persistent history stored in MongoDB Live UI updates — zero page refresh 🟢 Presence & Status Real-time online user list Instant connect/disconnect detection

📩 Notifications Per-conversation unread message counts Visual badge indicators in the sidebar 🔍 User Discovery Search users by name in real time 👤 Profile Management Update display name and bio Upload profile pictures via Cloudinary CDN ⚡ Performance & UX Lightning-fast builds with Vite Responsive across all screen sizes Clean UI with Tailwind CSS

---

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	18	Component-based UI framework
Vite	5	Build tool & lightning-fast dev server
Context API	—	Global state management
Axios	—	HTTP client for API calls
Socket.io Client	4	Real-time WebSocket communication
Tailwind CSS	—	Utility-first responsive styling

Backend

Technology	Version	Purpose
Node.js	20	JavaScript runtime
Express.js	4	REST API web framework
MongoDB	—	NoSQL document database
Mongoose	—	MongoDB object data modeling
Socket.io	4	Real-time WebSocket server
JSON Web Tokens	—	Stateless authentication
Bcrypt	—	Password hashing
Cloudinary	—	Cloud image storage & CDN

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                      CLIENT (React)                     │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │AuthContext│  │ChatContext│  │Pages / Components    │  │
│  └────┬─────┘  └────┬─────┘  └──────────────────────┘  │
│       │              │                                   │
│       │    Axios     │  Socket.io Client                 │
└───────┼──────────────┼───────────────────────────────────┘
        │              │
        ▼              ▼
┌───────────────────────────────────────────────┐
│              SERVER (Node + Express)           │
│                                               │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Routes  │→ │Controllers│→ │ Middleware │  │
│  └──────────┘  └────┬─────┘  └────────────┘  │
│                     │                         │
│       ┌─────────────┼──────────────┐          │
│       ▼             ▼              ▼          │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐    │
│  │ MongoDB │  │Socket.io │  │Cloudinary│    │
│  │(Mongoose)│  │  Server  │  │   CDN    │    │
│  └─────────┘  └──────────┘  └──────────┘    │
└───────────────────────────────────────────────┘

Data Flow:

1. Client sends HTTP requests via Axios → Express route → Controller → MongoDB
2. Real-time events travel over WebSocket (Socket.io) bidirectionally
3. Profile images upload to Cloudinary and the URL is stored in MongoDB

---

📂 Project Structure

ChatApp/
│
├── 📁 client/                      # ⚛️  React frontend (Vite)
│   ├── 📁 context/
│   │   ├── AuthContext.jsx          # 🔐 Auth state & actions
│   │   └── ChatContext.jsx          # 💬 Chat state & socket events
│   │
│   └── 📁 src/
│       ├── 📁 assets/               # 🖼️  Static assets
│       ├── 📁 components/
│       │   ├── ChatContainer.jsx    # 💬 Main message window and chats 
│       │   ├── Sidebar.jsx          # 👥 User list & search bar
│       │   └── RightSidebar.jsx     # ℹ️  Selected user info panel
│       │
│       ├── 📁 pages/
│       │   ├── HomePage.jsx         # 🏠 Main chat layout
│       │   ├── LoginPage.jsx        # 🔑 Auth page (login/signup)
│       │   └── ProfilePage.jsx      # 👤 Profile management
│       │
│       ├── App.jsx                  # 🔀 Routes & context providers
│       ├── main.jsx                 # 🚀 React entry point
│       └── index.css                # 🎨 Global styles
│
├── 📁 server/                       # 🟢 Node.js backend
│   ├── 📁 controllers/
│   │   ├── messageController.js     # 📨 Message send/get logic
│   │   └── userController.js        # 👤 User auth & profile logic
│   │
│   ├── 📁 middleware/
│   │   └── auth.js                  # 🛡️  JWT verification middleware
│   │
│   ├── 📁 models/
│   │   ├── Message.js               # 📄 Message Mongoose schema
│   │   └── User.js                  # 📄 User Mongoose schema
│   │
│   ├── 📁 routes/
│   │   ├── messageRoutes.js         # 📡 /api/messages/* endpoints
│   │   └── userRoutes.js            # 📡 /api/users/* endpoints
│   │
│   ├── 📁 lib/
│   │   ├── db.js                    # 🗄️  MongoDB connection setup
│   │   ├── cloudinary.js            # ☁️  Cloudinary config
│   │   └── utils.js                 # 🔧 Helper utilities
│   │
│   └── server.js                    # ⚡ Express + Socket.io entry
│
└── README.md

---

🚀 Getting Started

Prerequisites

Tool	Version	Link
Node.js	v18+	nodejs.org
npm	v9+	npmjs.com
Git	Latest	git-scm.com
MongoDB Atlas	Free tier	mongodb.com/atlas
Cloudinary	Free tier	cloudinary.com

---

Step-by-Step Setup

① Clone the repository

git clone https://github.com/Riyaban583/ChatApp.git
cd ChatApp

② Install dependencies

# Backend
cd server && npm install

# Frontend
cd ../client && npm install

③ Configure environment variables

# Create .env in /server (see Environment Variables section)
touch server/.env

④ Run the application

# Terminal 1 — Backend
cd server && npm run dev

# Terminal 2 — Frontend
cd client && npm run dev

⑤ Open in browser

Service	URL
🌐 Frontend	http://localhost:5173
⚙️ Backend API	http://localhost:5000

---

🔑 Environment Variables

Create a .env file inside the /server folder:

# ┌─────────────────────────────────────┐
# │             SERVER CONFIG            │
# └─────────────────────────────────────┘
PORT=5000

# ┌─────────────────────────────────────┐
# │           DATABASE (MongoDB)         │
# └─────────────────────────────────────┘
MONGO_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/chatapp

# ┌─────────────────────────────────────┐
# │         AUTHENTICATION (JWT)         │
# └─────────────────────────────────────┘
JWT_SECRET=your_super_secret_key_here_make_it_long_and_random

# ┌─────────────────────────────────────┐
# │        IMAGE STORAGE (Cloudinary)    │
# └─────────────────────────────────────┘
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

⚠️ Security Warning: Never commit .env to version control. Add it to .gitignore and rotate any secrets that are accidentally exposed.

---

📡 API Reference

👤 User Endpoints

Method	Endpoint	Auth	Description
POST	/api/users/signup	❌ Public	Register a new user
POST	/api/users/login	❌ Public	Login and receive JWT token
GET	/api/users/check	✅ JWT	Verify current auth token
PUT	/api/users/update-profile	✅ JWT	Update profile name / avatar

💬 Message Endpoints

Method	Endpoint	Auth	Description
POST	/api/messages/send	✅ JWT	Send a new message
GET	/api/messages/:id	✅ JWT	Fetch full conversation history

✅ Protected routes require Authorization: Bearer <token> in the request header.

---

🔌 Socket Events

Client ──────────────────────────────────────── Server
  │                                                │
  │──── connection ────────────────────────────►  │
  │                                                │
  │  ◄──── getOnlineUsers [ userId[] ] ──────────  │
  │                                                │
  │──── sendMessage { to, text } ──────────────►  │
  │                                                │
  │  ◄──── newMessage { from, text, timestamp } ─  │
  │                                                │
  │──── disconnect ─────────────────────────────►  │
  │                                                │
  │  ◄──── getOnlineUsers (updated) ─────────────  │

Event	Direction	Payload	Description
connection	Client → Server	—	User establishes WebSocket connection
getOnlineUsers	Server → Client	userId[]	Broadcasts updated list of online users
newMessage	Server → Client	message	Delivers incoming message in real time
disconnect	Client → Server	—	User disconnects; status updated for all

---

Completed ✅

• 💬 Real-time messaging via Socket.io
• 🔐 JWT authentication & protected routes
• 🖼️ Profile image upload (Cloudinary)
• 🟢 Live online/offline status indicators
• 📩 Unread message counters
• 🔍 User search by name

Coming Soon 🚧

• ⌨️ Typing indicators
• ✅ Message read receipts (seen status)
• 👥 Group chat rooms
• 📎 File & media attachment sharing
• 🔔 Browser push notifications
• 🎥 Voice & video calling (WebRTC)
• 🌙 Dark / light mode toggle
• 📱 Progressive Web App (PWA) support
• 🌍 Multi-language support (i18n) in chat app

---

☁️ Deployment

Frontend — Deploy /client

Platform	Notes
Vercel ⭐	Zero config for Vite, instant deploys, recommended
Netlify	Great free tier, good alternative

Backend — Deploy /server

Platform	Notes
Render ⭐	Free tier available, recommended for beginners
Railway	Simple deploys, excellent DX
AWS EC2	Production-grade, full control

Database

💡 Pro Tip: Set all environment variables in your hosting provider's settings dashboard — never hardcode secrets in your codebase.

---

👩‍💻 Author

Riya Bansal

Full Stack Developer

Built with ❤️ and lots of ☕

---

⭐ Support This Project

If ChatApp helped you learn or saved you time, a GitHub star goes a long way!