ChatFlow - Real-time Chat Application

A modern, production-ready real-time chat application built with React.js, Node.js, Express, and Socket.IO.

🚀 Features

Core Functionality

• Real-time messaging with Socket.IO
• Multi-user support with live user list
• Typing indicators showing who's currently typing
• User join/leave notifications with sound alerts
• Message timestamps with smart formatting
• Auto-scroll to latest messages
• Input validation and message sanitization

User Experience

• Responsive design for mobile, tablet, and desktop
• Dark/light mode toggle with system preference detection
• Emoji picker with popular emojis
• Sound notifications for new messages
• Connection status indicators
• Rate limiting and spam protection

Technical Features

• Clean architecture with separated concerns
• TypeScript for type safety
• Real-time WebSocket communication
• Session persistence with localStorage
• Error handling and graceful degradation
• Memory-efficient message management

🛠️ Tech Stack

Frontend

• React 18 with TypeScript
• TailwindCSS for styling
• Socket.IO Client for real-time communication
• Lucide React for icons
• Vite for development and building

Backend

• Node.js with Express.js
• Socket.IO for WebSocket communication
• CORS for cross-origin requests
• Helmet for security headers
• Express Rate Limit for API protection

📦 Installation & Setup

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

1. Clone and Install Dependencies

# Install frontend dependencies
npm install

# Install backend dependencies
cd server
npm install
cd ..

2. Start the Development Servers

Backend Server (Port 5000)

cd server
npm start

Frontend Server (Port 5173)

npm run dev

3. Access the Application

• Frontend: http://localhost:5173
• Backend API: http://localhost:5000
• Health Check: http://localhost:5000/health

🎯 Usage

1. Join the Chat: Enter a unique username (2-20 characters)
2. Send Messages: Type your message and press Enter or click Send
3. See Who's Online: Check the user list sidebar
4. Typing Indicators: See when others are typing
5. Emoji Support: Click the smile icon to add emojis
6. Theme Toggle: Switch between light and dark modes
7. Notifications: Get notified when users join/leave or send messages

🏗️ Project Structure

├── src/                          # Frontend source code
│   ├── components/               # React components
│   │   ├── ChatInterface.tsx     # Main chat container
│   │   ├── ChatHeader.tsx        # Header with user info
│   │   ├── MessageList.tsx       # Message display area
│   │   ├── MessageBubble.tsx     # Individual message component
│   │   ├── MessageInput.tsx      # Message input with emoji picker
│   │   ├── UserList.tsx          # Online users sidebar
│   │   ├── TypingIndicator.tsx   # Shows typing users
│   │   ├── NotificationCenter.tsx # Toast notifications
│   │   └── LoginPage.tsx         # Username entry page
│   ├── contexts/                 # React contexts
│   │   ├── SocketContext.tsx     # Socket.IO connection
│   │   └── ThemeContext.tsx      # Dark/light theme
│   ├── types/                    # TypeScript definitions
│   │   └── chat.ts               # Chat-related types
│   ├── utils/                    # Utility functions
│   │   └── dateUtils.ts          # Date formatting helpers
│   └── App.tsx                   # Main app component
├── server/                       # Backend source code
│   ├── sockets/                  # Socket.IO handlers
│   │   └── socketHandlers.js     # Connection and message handling
│   ├── utils/                    # Server utilities
│   │   ├── userManager.js        # User session management
│   │   └── messageManager.js     # Message handling and validation
│   ├── package.json              # Backend dependencies
│   └── server.js                 # Express server setup
└── README.md                     # This file

🔧 Configuration

Environment Variables

The application works out of the box with these default configurations:

• Frontend Port: 5173 (Vite default)
• Backend Port: 5000
• Socket.IO Transport: WebSocket with polling fallback

Customization

You can customize various aspects:

1. Server Port: Change PORT in server/server.js
2. Socket URL: Update the connection URL in src/contexts/SocketContext.tsx
3. Message Limits: Modify limits in server/utils/messageManager.js
4. Rate Limiting: Adjust limits in server/server.js

🚀 Production Deployment

Backend Deployment

1. Set environment variables:

   • PORT (default: 5000)
   • NODE_ENV=production

2. Update CORS settings in server/server.js to match your frontend domain

Frontend Deployment

1. Update the Socket.IO connection URL in src/contexts/SocketContext.tsx
2. Build the application: npm run build
3. Serve the dist folder with a static file server

Security Considerations

• Enable HTTPS in production
• Configure proper CORS origins
• Set up rate limiting
• Use environment variables for sensitive config
• Consider adding authentication for user management

🔍 API Endpoints

REST API

• GET /health - Server health check with statistics

Socket.IO Events

Client → Server

• join - Join chat with username
• sendMessage - Send a new message
• typing - Toggle typing indicator
• ping - Connection health check

Server → Client

• newMessage - Broadcast new message
• userJoined - User joined notification
• userLeft - User left notification
• userListUpdate - Updated list of online users
• userTyping - Typing indicator update

🧪 Features in Detail

Real-time Communication

• Instant message delivery using WebSocket
• Automatic reconnection on connection loss
• Typing indicators with smart timeout
• Connection status monitoring

User Management

• Unique username validation
• Session persistence across page reloads
• Online user tracking
• Join/leave notifications

Message Features

• Message length validation (1000 chars max)
• HTML sanitization for security
• Timestamp formatting (smart relative time)
• Auto-scroll to latest messages
• Message history (last 1000 messages)

UI/UX Enhancements

• Responsive design for all screen sizes
• Dark/light theme with system preference
• Smooth animations and transitions
• Accessible keyboard navigation
• Sound notifications (can be disabled)
• Emoji picker with popular emojis

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test them
4. Commit your changes: git commit -m 'Add feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Socket.IO team for the excellent real-time library
• Tailwind CSS for the utility-first CSS framework
• Lucide React for the beautiful icon set
• React team for the amazing frontend library

---

Made by ❤️ with Ajay Dhangar using React, Node.js, and Socket.IO