{"id":51582811,"url":"https://github.com/elyse502/real-time-chat-app","last_synced_at":"2026-07-11T07:31:00.284Z","repository":{"id":359738587,"uuid":"1244481986","full_name":"elyse502/real-time-chat-app","owner":"elyse502","description":"A full-stack real-time chat application built with Node.js, Socket.IO, React, TypeScript, and Tailwind CSS featuring room-based messaging, typing indicators, live user tracking, responsive UI, and scalable modular architecture.","archived":false,"fork":false,"pushed_at":"2026-05-23T08:00:34.000Z","size":141,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T09:06:16.261Z","etag":null,"topics":["backend","chat-application","event-driven","expressjs","frontend","fullstack","nodejs","react","react-context-api","realtime-chat","realtime-communication","responsive-ui","socketio","socketio-client","tailwindcss","typescript","typescript-project","vite","websocket","websocket-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elyse502.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T09:58:28.000Z","updated_at":"2026-05-23T08:59:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/elyse502/real-time-chat-app","commit_stats":null,"previous_names":["elyse502/real-time-chat-app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/elyse502/real-time-chat-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyse502%2Freal-time-chat-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyse502%2Freal-time-chat-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyse502%2Freal-time-chat-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyse502%2Freal-time-chat-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elyse502","download_url":"https://codeload.github.com/elyse502/real-time-chat-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elyse502%2Freal-time-chat-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35355110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","chat-application","event-driven","expressjs","frontend","fullstack","nodejs","react","react-context-api","realtime-chat","realtime-communication","responsive-ui","socketio","socketio-client","tailwindcss","typescript","typescript-project","vite","websocket","websocket-server"],"created_at":"2026-07-11T07:31:00.169Z","updated_at":"2026-07-11T07:31:00.276Z","avatar_url":"https://github.com/elyse502.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 💬 Real-Time Chat Application 🌐\n\n## A Production-Grade WebSocket-Powered Messaging Platform\n\n![React](https://img.shields.io/badge/React-19.x-61DAFB?style=for-the-badge\u0026logo=react\u0026logoColor=black)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)\n![Socket.IO](https://img.shields.io/badge/Socket.IO-4.x-010101?style=for-the-badge\u0026logo=socket.io\u0026logoColor=white)\n![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?style=for-the-badge\u0026logo=vite\u0026logoColor=white)\n![Tailwind CSS](https://img.shields.io/badge/Tailwind-3.x-38B2AC?style=for-the-badge\u0026logo=tailwind-css\u0026logoColor=white)\n![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)\n\n### **Built with Modern Web Technologies:**\n\n![WebSockets](https://img.shields.io/badge/WebSockets-Real_Time-FF6B6B?style=flat-square\u0026logo=websocket\u0026logoColor=white)\n![Event-Driven](https://img.shields.io/badge/Event-Driven-Architecture-4CAF50?style=flat-square\u0026logo=events\u0026logoColor=white)\n![Bidirectional](https://img.shields.io/badge/Bidirectional-Communication-1E90FF?style=flat-square\u0026logo=exchange\u0026logoColor=white)\n![Type Safety](https://img.shields.io/badge/Type-Safe-Full-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)\n\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n\n- [💬 Real-Time Chat Application 🌐](#-real-time-chat-application-)\n  - [A Production-Grade WebSocket-Powered Messaging Platform](#a-production-grade-websocket-powered-messaging-platform)\n    - [**Built with Modern Web Technologies:**](#built-with-modern-web-technologies)\n  - [📋 Table of Contents](#-table-of-contents)\n  - [🎯 Project Overview](#-project-overview)\n    - [Key Differentiators](#key-differentiators)\n  - [✨ Features](#-features)\n  - [🛠️ Tech Stack](#️-tech-stack)\n    - [Frontend](#frontend)\n    - [Backend](#backend)\n  - [🏗️ System Architecture](#️-system-architecture)\n  - [📁 Project Structure](#-project-structure)\n  - [🎨 Core Features Deep Dive](#-core-features-deep-dive)\n    - [1. Real-Time Messaging 💬](#1-real-time-messaging-)\n    - [2. Room-Based Communication 🏠](#2-room-based-communication-)\n    - [3. Typing Indicators ⌨️](#3-typing-indicators-️)\n    - [4. Live User Tracking 👥](#4-live-user-tracking-)\n    - [5. Message History 📜](#5-message-history-)\n  - [🔌 Socket Events](#-socket-events)\n    - [Client → Server Events](#client--server-events)\n    - [Server → Client Events](#server--client-events)\n  - [🏛️ Backend Architecture](#️-backend-architecture)\n    - [Layered Design](#layered-design)\n    - [Service Layer Example](#service-layer-example)\n  - [🎭 Frontend Architecture](#-frontend-architecture)\n    - [Component Hierarchy](#component-hierarchy)\n    - [Context Structure](#context-structure)\n    - [Custom Hooks](#custom-hooks)\n  - [⚙️ Installation \\\u0026 Setup](#️-installation--setup)\n    - [Prerequisites](#prerequisites)\n    - [Quick Start](#quick-start)\n  - [🔧 Configuration](#-configuration)\n    - [Backend Environment (.env)](#backend-environment-env)\n    - [Frontend Environment (.env)](#frontend-environment-env)\n  - [📊 Validation Rules](#-validation-rules)\n    - [Validation Implementation](#validation-implementation)\n  - [🎨 User Experience Highlights](#-user-experience-highlights)\n  - [📈 Performance Optimizations](#-performance-optimizations)\n  - [🔮 Future Roadmap](#-future-roadmap)\n  - [📚 Learning Outcomes](#-learning-outcomes)\n  - [👨‍💻 Author](#-author)\n    - [**Elysée NIYIBIZI**](#elysée-niyibizi)\n  - [📄 License](#-license)\n  - [🙏 Acknowledgments](#-acknowledgments)\n    - [⭐ Star this repository if it helped you learn real-time application development!](#-star-this-repository-if-it-helped-you-learn-real-time-application-development)\n\n---\n\n## 🎯 Project Overview\n\nA **production-ready real-time chat platform** demonstrating modern WebSocket architecture, full-stack TypeScript development, and responsive UI design. This application enables users to join chat rooms, exchange messages instantly, view active participants, and experience seamless live communication.\n\n### Key Differentiators\n\n| Aspect               | Implementation                        |\n| -------------------- | ------------------------------------- |\n| **Communication**    | Real-time WebSocket with Socket.IO    |\n| **Architecture**     | Clean separation of concerns          |\n| **Type Safety**      | Full TypeScript across stack          |\n| **State Management** | React Context API                     |\n| **Styling**          | Responsive Tailwind CSS               |\n| **Persistence**      | In-memory with planned DB integration |\n\n---\n\n## ✨ Features\n\n| Category                  | Feature                          | Status |\n| ------------------------- | -------------------------------- | ------ |\n| **Messaging**             | Real-time message exchange       | ✅     |\n| **Rooms**                 | Multiple chat rooms support      | ✅     |\n| **User Tracking**         | Live participant list per room   | ✅     |\n| **Typing Indicators**     | Real-time typing status          | ✅     |\n| **Message History**       | Previous conversations per room  | ✅     |\n| **Auto-Scroll**           | Automatic scroll to new messages | ✅     |\n| **System Notifications**  | Join/leave event broadcasting    | ✅     |\n| **Username Persistence**  | Local storage username storage   | ✅     |\n| **Connection Monitoring** | Real-time connection status      | ✅     |\n| **Responsive Design**     | Mobile, tablet, desktop support  | ✅     |\n| **Type Safety**           | Full TypeScript implementation   | ✅     |\n| **Toast Notifications**   | User-friendly feedback system    | ✅     |\n\n---\n\n## 🛠️ Tech Stack\n\n\u003cdiv align=\"center\"\u003e\n\n### Frontend\n\n| Technology           | Version | Purpose       | Badge                                                                                             |\n| -------------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------- |\n| **React**            | 19.x    | UI Library    | ![React](https://img.shields.io/badge/React-19.x-61DAFB?logo=react\u0026logoColor=black)               |\n| **TypeScript**       | 5.x     | Type Safety   | ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white) |\n| **Vite**             | 5.x     | Build Tool    | ![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?logo=vite\u0026logoColor=white)                   |\n| **Tailwind CSS**     | 3.x     | Styling       | ![Tailwind](https://img.shields.io/badge/Tailwind-3.x-38B2AC?logo=tailwind-css\u0026logoColor=white)   |\n| **Socket.IO Client** | 4.x     | Real-time     | ![Socket.IO](https://img.shields.io/badge/Socket.IO-4.x-010101?logo=socket.io\u0026logoColor=white)    |\n| **React Hot Toast**  | 2.x     | Notifications | ![Toast](https://img.shields.io/badge/Toast-2.x-FF5F6D?logo=react\u0026logoColor=white)                |\n\n### Backend\n\n| Technology     | Version | Purpose            | Badge                                                                                             |\n| -------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------------- |\n| **Node.js**    | 18+     | Runtime            | ![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js\u0026logoColor=white)        |\n| **Express.js** | 4.x     | Web Framework      | ![Express](https://img.shields.io/badge/Express-4.x-000000?logo=express\u0026logoColor=white)          |\n| **Socket.IO**  | 4.x     | WebSocket Server   | ![Socket.IO](https://img.shields.io/badge/Socket.IO-4.x-010101?logo=socket.io\u0026logoColor=white)    |\n| **TypeScript** | 5.x     | Type Safety        | ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white) |\n| **dotenv**     | 16.x    | Environment Config | ![dotenv](https://img.shields.io/badge/dotenv-16.x-ECD53F?logo=dotenv\u0026logoColor=black)            |\n\n\u003c/div\u003e\n\n---\n\n## 🏗️ System Architecture\n\n```console\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                              FRONTEND (React)                               │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                         UI Components                                │   │\n│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │   │\n│  │  │RoomList  │ │MessageList│ │MessageInput│ │ChatHeader│ │UsernameForm│ │   │\n│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                    │                                        │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                         Context API                                  │   │\n│  │  • ChatContext (messages, users, typing status)                     │   │\n│  │  • SocketContext (connection management)                            │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                    │                                        │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                      Socket.IO Client                                │   │\n│  │  • Emits events to server                                           │   │\n│  │  • Listens for server events                                        │   │\n│  │  • Manages reconnection                                             │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n└─────────────────────────────────┬───────────────────────────────────────────┘\n                                  │\n                    WebSocket (ws:// or wss://)\n                                  │\n┌─────────────────────────────────┴───────────────────────────────────────────┐\n│                              BACKEND (Node.js)                              │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                       Socket.IO Server                               │   │\n│  │  • Manages client connections                                       │   │\n│  │  • Routes events to handlers                                        │   │\n│  │  • Broadcasts to rooms                                              │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                    │                                        │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                         Services Layer                               │   │\n│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                │   │\n│  │  │RoomService   │ │MessageService│ │UserService   │                │   │\n│  │  └──────────────┘ └──────────────┘ └──────────────┘                │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                    │                                        │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                         Data Models                                  │   │\n│  │  • Room (id, name, users, messages)                                 │   │\n│  │  • Message (id, userId, text, timestamp)                            │   │\n│  │  • User (id, username, roomId)                                      │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 📁 Project Structure\n\n```console\nreal-time-chat-app/\n│\n├── 📁 backend/                          # Node.js + Express + Socket.IO\n│   ├── 📁 src/\n│   │   ├── 📁 config/\n│   │   │   └── 📄 constants.ts         # Application constants\n│   │   ├── 📁 models/\n│   │   │   ├── 📄 room.model.ts        # Room data structure\n│   │   │   ├── 📄 message.model.ts     # Message data structure\n│   │   │   └── 📄 user.model.ts        # User data structure\n│   │   ├── 📁 services/\n│   │   │   ├── 📄 room.service.ts      # Room business logic\n│   │   │   ├── 📄 message.service.ts   # Message business logic\n│   │   │   └── 📄 user.service.ts      # User business logic\n│   │   ├── 📁 sockets/\n│   │   │   └── 📄 chat.socket.ts       # Socket event handlers\n│   │   ├── 📁 types/\n│   │   │   └── 📄 index.ts             # TypeScript interfaces\n│   │   ├── 📁 utils/\n│   │   │   └── 📄 validators.ts        # Input validation\n│   │   ├── 📄 app.ts                   # Express app configuration\n│   │   └── 📄 server.ts                # Server entry point\n│   ├── 📄 package.json                  # Backend dependencies\n│   ├── 📄 tsconfig.json                 # TypeScript config\n│   └── 📄 .env                          # Environment variables\n│\n├── 📁 frontend/                         # React + Vite + Tailwind\n│   ├── 📁 src/\n│   │   ├── 📁 components/\n│   │   │   ├── 📁 Chat/\n│   │   │   │   ├── 📄 ChatContainer.tsx\n│   │   │   │   ├── 📄 MessageList.tsx\n│   │   │   │   ├── 📄 MessageInput.tsx\n│   │   │   │   └── 📄 TypingIndicator.tsx\n│   │   │   ├── 📁 Room/\n│   │   │   │   ├── 📄 RoomList.tsx\n│   │   │   │   └── 📄 RoomItem.tsx\n│   │   │   ├── 📁 Layout/\n│   │   │   │   ├── 📄 ChatHeader.tsx\n│   │   │   │   └── 📄 Sidebar.tsx\n│   │   │   └── 📁 UI/\n│   │   │       ├── 📄 ConnectionStatus.tsx\n│   │   │       └── 📄 UsernameForm.tsx\n│   │   ├── 📁 context/\n│   │   │   ├── 📄 ChatContext.tsx      # Chat state management\n│   │   │   └── 📄 SocketContext.tsx    # Socket connection management\n│   │   ├── 📁 hooks/\n│   │   │   ├── 📄 useSocket.ts         # Socket lifecycle hook\n│   │   │   └── 📄 useLocalStorage.ts   # Persistent storage hook\n│   │   ├── 📁 layouts/\n│   │   │   └── 📄 MainLayout.tsx       # App layout wrapper\n│   │   ├── 📁 services/\n│   │   │   └── 📄 socket.ts            # Socket client initialization\n│   │   ├── 📁 types/\n│   │   │   └── 📄 index.ts             # TypeScript interfaces\n│   │   ├── 📄 App.tsx                  # Root component\n│   │   └── 📄 main.tsx                 # Entry point\n│   ├── 📁 public/                       # Static assets\n│   ├── 📄 package.json                  # Frontend dependencies\n│   ├── 📄 vite.config.ts                # Vite configuration\n│   └── 📄 .env                          # Environment variables\n│\n├── 📄 .gitignore                        # Git ignore rules\n└── 📄 README.md                         # Documentation\n```\n\n---\n\n## 🎨 Core Features Deep Dive\n\n### 1. Real-Time Messaging 💬\n\nUsers send and receive messages instantly using WebSockets powered by Socket.IO.\n\n```typescript\n// Client sends message\nsocket.emit(\"send_message\", { roomId, message, username });\n\n// Server broadcasts to room\nio.to(roomId).emit(\"receive_message\", {\n  id: uuid(),\n  username,\n  text: message,\n  timestamp: new Date(),\n});\n```\n\n### 2. Room-Based Communication 🏠\n\nUsers join independent chat rooms for organized conversations.\n\n```typescript\n// Join room\nsocket.emit(\"join_room\", { roomId, username });\n\n// Server manages room membership\nsocket.join(roomId);\nio.to(roomId).emit(\"user_joined\", { username });\n```\n\n### 3. Typing Indicators ⌨️\n\nReal-time typing status shows who is actively typing.\n\n```typescript\n// Client on keypress\nsocket.emit(\"start_typing\", { roomId, username });\n\n// Server broadcasts\nsocket.broadcast.to(roomId).emit(\"user_typing\", { username });\n```\n\n### 4. Live User Tracking 👥\n\nEach room displays all currently connected users.\n\n```typescript\n// Track users per room\nconst roomUsers = new Map\u003cstring, Set\u003cstring\u003e\u003e();\n\n// Broadcast updates\nio.to(roomId).emit(\"room_users\", Array.from(roomUsers.get(roomId)));\n```\n\n### 5. Message History 📜\n\nUsers receive previous conversation history when joining.\n\n```typescript\n// Store messages per room\nconst messageHistory = new Map\u003cstring, Message[]\u003e();\n\n// Send history on join\nsocket.emit(\"message_history\", messageHistory.get(roomId));\n```\n\n---\n\n## 🔌 Socket Events\n\n### Client → Server Events\n\n| Event          | Payload                                                 | Description               |\n| -------------- | ------------------------------------------------------- | ------------------------- |\n| `get_rooms`    | `{}`                                                    | Fetch all available rooms |\n| `join_room`    | `{ roomId: string, username: string }`                  | Join a specific room      |\n| `send_message` | `{ roomId: string, message: string, username: string }` | Send a message to room    |\n| `start_typing` | `{ roomId: string, username: string }`                  | Notify typing started     |\n| `stop_typing`  | `{ roomId: string, username: string }`                  | Notify typing stopped     |\n\n### Server → Client Events\n\n| Event             | Payload                | Description                 |\n| ----------------- | ---------------------- | --------------------------- |\n| `rooms_list`      | `Room[]`               | List of available rooms     |\n| `receive_message` | `Message`              | Incoming message            |\n| `message_history` | `Message[]`            | Previous room messages      |\n| `room_users`      | `User[]`               | Active room participants    |\n| `user_joined`     | `{ username: string }` | User joined notification    |\n| `user_left`       | `{ username: string }` | User left notification      |\n| `user_typing`     | `{ username: string }` | Typing activity indicator   |\n| `error`           | `{ message: string }`  | Validation or server errors |\n\n---\n\n## 🏛️ Backend Architecture\n\n### Layered Design\n\n| Layer        | Responsibility                      | Files            |\n| ------------ | ----------------------------------- | ---------------- |\n| **Config**   | Application constants \u0026 environment | `constants.ts`   |\n| **Models**   | Data structures \u0026 interfaces        | `*.model.ts`     |\n| **Services** | Business logic \u0026 data management    | `*.service.ts`   |\n| **Sockets**  | Event handlers \u0026 communication      | `chat.socket.ts` |\n| **Utils**    | Helper functions \u0026 validators       | `validators.ts`  |\n| **Types**    | Shared TypeScript interfaces        | `index.ts`       |\n\n### Service Layer Example\n\n```typescript\n// room.service.ts\nexport class RoomService {\n  private rooms: Map\u003cstring, Room\u003e = new Map();\n\n  getAllRooms(): Room[] {\n    return Array.from(this.rooms.values());\n  }\n\n  getRoom(roomId: string): Room | undefined {\n    return this.rooms.get(roomId);\n  }\n\n  addUserToRoom(roomId: string, user: User): void {\n    const room = this.rooms.get(roomId);\n    if (room) {\n      room.users.push(user);\n    }\n  }\n}\n```\n\n---\n\n## 🎭 Frontend Architecture\n\n### Component Hierarchy\n\n```console\nApp\n├── SocketProvider\n│   └── ChatProvider\n│       └── MainLayout\n│           ├── Sidebar\n│           │   ├── UsernameForm\n│           │   └── RoomList\n│           │       └── RoomItem[]\n│           └── ChatContainer\n│               ├── ChatHeader\n│               │   ├── RoomName\n│               │   └── ConnectionStatus\n│               ├── MessageList\n│               │   └── Message[]\n│               ├── TypingIndicator\n│               └── MessageInput\n```\n\n### Context Structure\n\n```typescript\n// ChatContext.tsx\ninterface ChatContextType {\n  currentRoom: Room | null;\n  messages: Message[];\n  users: User[];\n  typingUsers: string[];\n  sendMessage: (text: string) =\u003e void;\n  joinRoom: (roomId: string) =\u003e void;\n  startTyping: () =\u003e void;\n  stopTyping: () =\u003e void;\n}\n```\n\n### Custom Hooks\n\n```typescript\n// useSocket.ts\nexport const useSocket = () =\u003e {\n  const [isConnected, setIsConnected] = useState(false);\n\n  useEffect(() =\u003e {\n    socket.on(\"connect\", () =\u003e setIsConnected(true));\n    socket.on(\"disconnect\", () =\u003e setIsConnected(false));\n\n    return () =\u003e {\n      socket.off(\"connect\");\n      socket.off(\"disconnect\");\n    };\n  }, []);\n\n  return { socket, isConnected };\n};\n```\n\n---\n\n## ⚙️ Installation \u0026 Setup\n\n### Prerequisites\n\n- ✅ **Node.js** (v18 or higher)\n- ✅ **npm** or **yarn** package manager\n- ✅ **Git** (for cloning)\n- ✅ **Modern web browser**\n\n### Quick Start\n\n```console\n# 1. Clone the repository\ngit clone https://github.com/elyse502/real-time-chat-app.git\n\n# 2. Navigate to project directory\ncd real-time-chat-app\n\n# 3. Setup Backend\ncd backend\nnpm install\ncp .env.example .env  # Configure environment variables\n\n# 4. Setup Frontend\ncd ../frontend\nnpm install\ncp .env.example .env  # Configure environment variables\n\n# 5. Run Development Servers\n# Terminal 1 - Backend (from backend directory)\nnpm run dev\n\n# Terminal 2 - Frontend (from frontend directory)\nnpm run dev\n\n# 6. Open Application\n# Frontend: http://localhost:5173\n# Backend: http://localhost:3000\n```\n\n---\n\n## 🔧 Configuration\n\n### Backend Environment (.env)\n\n```env\n# Server Configuration\nPORT=3000\nNODE_ENV=development\n\n# Client Configuration\nCLIENT_URL=http://localhost:5173\n\n# Socket Configuration\nSOCKET_PING_TIMEOUT=60000\nSOCKET_PING_INTERVAL=25000\n```\n\n### Frontend Environment (.env)\n\n```env\n# API Configuration\nVITE_API_URL=http://localhost:3000\n\n# Socket Configuration\nVITE_SOCKET_PATH=/socket.io\n```\n\n---\n\n## 📊 Validation Rules\n\n| Field        | Type   | Rules                       | Error Message                                 |\n| ------------ | ------ | --------------------------- | --------------------------------------------- |\n| **Username** | string | Min: 3 chars, Max: 20 chars | \"Username must be 3-20 characters\"            |\n| **Message**  | string | Min: 1 char, Max: 500 chars | \"Message cannot be empty or exceed 500 chars\" |\n| **Room ID**  | string | Must exist in system        | \"Room does not exist\"                         |\n\n### Validation Implementation\n\n```typescript\n// Backend validator\nexport const validateUsername = (username: string): boolean =\u003e {\n  return username.length \u003e= 3 \u0026\u0026 username.length \u003c= 20;\n};\n\nexport const validateMessage = (message: string): boolean =\u003e {\n  return message.length \u003e= 1 \u0026\u0026 message.length \u003c= 500;\n};\n```\n\n---\n\n## 🎨 User Experience Highlights\n\n| Feature                   | Implementation                     | Benefit                    |\n| ------------------------- | ---------------------------------- | -------------------------- |\n| **Auto-Scroll**           | `scrollIntoView()` on new messages | Always see latest messages |\n| **Toast Notifications**   | React Hot Toast                    | Non-intrusive feedback     |\n| **Connection Monitoring** | Socket event listeners             | Real-time status awareness |\n| **Typing Indicators**     | Debounced emit events              | Reduced network traffic    |\n| **Room Updates**          | Real-time participant lists        | Always accurate user count |\n| **Responsive Layout**     | Tailwind breakpoints               | Works on all devices       |\n| **Username Persistence**  | LocalStorage                       | No re-entry on refresh     |\n\n---\n\n## 📈 Performance Optimizations\n\n| Optimization           | Implementation                 | Impact                       |\n| ---------------------- | ------------------------------ | ---------------------------- |\n| **Message Throttling** | Rate limiting per user         | Prevents spam                |\n| **Debounced Typing**   | 300ms debounce                 | Reduces 90% of typing events |\n| **Virtual Scrolling**  | For large message history      | Smooth rendering             |\n| **Lazy Loading**       | Code splitting with React.lazy | Faster initial load          |\n| **Socket Compression** | perMessageDeflate enabled      | Reduced bandwidth            |\n| **Connection Pooling** | Reuse socket connections       | Lower memory usage           |\n\n---\n\n## 🔮 Future Roadmap\n\n| Feature                    | Priority | Description                 |\n| -------------------------- | -------- | --------------------------- |\n| 🔐 **JWT Authentication**  | High     | Secure user authentication  |\n| 🗄️ **MongoDB Persistence** | High     | Persistent message storage  |\n| 💬 **Private Messaging**   | High     | Direct user-to-user chats   |\n| 📎 **File Sharing**        | Medium   | Image and file attachments  |\n| 🐳 **Docker Support**      | Medium   | Containerized deployment    |\n| 📊 **Redis Scaling**       | Medium   | Horizontal scaling support  |\n| 🧪 **Testing Suite**       | Medium   | Unit \u0026 integration tests    |\n| 🔄 **CI/CD Pipeline**      | Low      | Automated deployment        |\n| 😊 **Message Reactions**   | Low      | Emoji reactions to messages |\n| 👤 **User Avatars**        | Low      | Profile pictures            |\n\n---\n\n## 📚 Learning Outcomes\n\nThis project demonstrates practical experience with:\n\n| Category              | Skills Demonstrated                    |\n| --------------------- | -------------------------------------- |\n| **WebSockets**        | Real-time, bidirectional communication |\n| **Full-Stack**        | End-to-end TypeScript development      |\n| **Socket.IO**         | Event handling, rooms, broadcasting    |\n| **React**             | Hooks, Context API, components         |\n| **Architecture**      | Separation of concerns, modular design |\n| **State Management**  | Context, local storage                 |\n| **Type Safety**       | Full TypeScript implementation         |\n| **Real-Time Systems** | Event-driven architecture              |\n| **Responsive Design** | Mobile-first approach                  |\n\n---\n\n## 👨‍💻 Author\n\n### **Elysée NIYIBIZI**\n\n_Junior Fullstack Software Engineer_\n\n\u003cdiv align=\"center\"\u003e\n\n[![Portfolio](https://img.shields.io/badge/Portfolio-elyseedev.netlify.app-000000?style=for-the-badge\u0026logo=vercel\u0026logoColor=white)](https://elyseedev.netlify.app)\n[![GitHub](https://img.shields.io/badge/GitHub-elyse502-181717?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/elyse502)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Niyibizi_Elysée-0A66C2?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://linkedin.com/in/niyibizi-elysée)\n[![Email](https://img.shields.io/badge/Email-elyseniyibizi502@gmail.com-D14836?style=for-the-badge\u0026logo=gmail\u0026logoColor=white)](mailto:elyseniyibizi502@gmail.com)\n\n\u003c/div\u003e\n\n**Specialties:**\n\n- Backend Development\n- Real-Time Systems\n- TypeScript Applications\n- MERN Stack Development\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](https://github.com/elyse502/real-time-chat-app/blob/main/LICENSE) file for details.\n\n```\nMIT License\n\nCopyright (c) 2026 Elysée NIYIBIZI\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction...\n```\n\n---\n\n## 🙏 Acknowledgments\n\n- **Socket.IO Team** - For the incredible real-time library\n- **React Team** - For the amazing UI framework\n- **TypeScript Team** - For type safety across the stack\n- **Open Source Community** - For continuous inspiration\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### ⭐ Star this repository if it helped you learn real-time application development!\n\n**Built with 💻, WebSockets, and Real-Time Passion**\n\n---\n\n_From concept to production - a complete real-time chat platform demonstrating modern web architecture_\n\n[⬆ Back to Top](#-table-of-contents)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyse502%2Freal-time-chat-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felyse502%2Freal-time-chat-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felyse502%2Freal-time-chat-app/lists"}