💬 VEVOX — Real-Time Chat Web Application

Transforming Conversations • Igniting Instant Collaboration

Built with the tools and technologies:

---

Table of Contents

• Overview
• UI Preview
• Key Features
• Project Structure
  • Project Index
• Getting Started
  • Prerequisites
  • Installation
  • Usage
  • Testing
• Learning Outcomes
• Roadmap
• Contributors
• Acknowledgments
• License

---

✨ Overview

Vevox – Real-Time Chat Web Application is a full-stack chat platform built on WebSockets for low-latency, bi-directional messaging. It provides real-time messaging, persistent MySQL-backed storage, and dynamic chatroom management for Q&A and group collaboration.

---

🎨 UI Preview

Chatroom Interface	Real-Time Messaging

---

🚀 Key Features

Feature	Description
💬 Real-Time Messaging (WebSocket)	webSocketServer.js provides low-latency, bi-directional messaging between clients and the server.
🧑‍🤝‍🧑 Room & Session Management	Dynamic room creation and joining, managed in server logic and persisted to the database.
🗄️ Persistent MySQL Storage	SQL migrations and test/database.sql define schemas for rooms, messages, and questions.
🧩 Separation of Concerns	htmlServer.js, webSocketServer.js and index.js keep frontend serving, sockets and routing modular.
🧪 Testing & Dev Utilities	test/serverSide.js and Mocha-based tests support server behaviour validation and CI checks.
⚡ Low Latency & Broadcast	Message broadcasting and efficient event routing for responsive chat UX.
🔒 Optional TLS / Secure Config	ca.pem and env-managed configs support local TLS testing and secure credentials handling.
🎨 Client Interface & Examples	html/ and example chatroom html & styling/ provide sample UI, scripts and styles for integration.
🧰 npm Scripts & Tooling	package.json exposes scripts for running servers, installing deps and running tests.
🌐 Cross-Platform	Works across macOS, Windows and Linux; README includes quick install snippets for each platform.

---

📁 Project Structure

└── vevox-real-time-chat-web-application/
├── Vevox Chatroom/
│   ├── example chatroom html & styling/
│   │   ├── newChatroom.html
│   │   └── newStyle.css
│   ├── html/
│   │   ├── Chatroom.html
│   │   ├── clientSide.js
│   │   ├── Index.html
│   │   ├── MessageEvents.js
│   │   ├── Send.png
│   │   └── style.css
│   ├── Migrations/
│   │   ├── 1-AddRoomName.sql
│   │   └── 2-AddQuestions.sql
│   ├── test/
│   │   ├── database.sql
│   │   └── serverSide.js
│   ├── htmlServer.js
│   ├── index.js
│   ├── package-lock.json
│   ├── package.json
│   └── webSocketServer.js
├── .gitignore
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
└── SECURITY.md

---

📑 Project Index

VEVOX-REAL-TIME-CHAT-WEB-APPLICATION/

__root__

• .gitignore — File.
• CODE_OF_CONDUCT.md — File.
• CONTRIBUTING.md — File.
• LICENSE — File.
• README.md — Project documentation, overview and setup instructions.
• SECURITY.md — File.

.github

• CODEOWNERS — File.

ISSUE_TEMPLATE

• bug_report.yml — File.
• config.yml — File.
• feature_request.yml — File.

PULL_REQUEST_TEMPLATE

• pull_request_template.yml — File.

scripts

• update-contributors.js — JavaScript file.

workflows

• ci.yml — File.
• update-contributors.yml — File.
• update-project-index.yml — File.
• update-project-structure.yml — File.
• update-tech-badges-single-repo.yml — File.

Vevox Chatroom

• htmlServer.js — Serves static frontend assets for the chat UI.
• index.js — Main server entrypoint that wires HTTP and WebSocket servers.
• package-lock.json — Lockfile with exact dependency versions.
• package.json — Npm manifest (dependencies & scripts).
• webSocketServer.js — WebSocket server that manages connections, broadcasts and hooks.

example chatroom html & styling

• newChatroom.html — Example chatroom page demonstrating layout and client-side integration.
• newStyle.css — Example stylesheet for the sample chatroom.

html

• Chatroom.html — Main chatroom UI page.
• clientSide.js — Client-side JS handling WebSocket events and UI updates.
• Index.html — Login/landing page for users.
• MessageEvents.js — Structured WebSocket message/event types.
• Send.png — File.
• style.css — Stylesheet for the HTML UI.

Migrations

• 1-AddRoomName.sql — Adds room name column/table changes.
• 2-AddQuestions.sql — Adds question support schema.

test

• database.sql — SQL for testing DB schemas and sample data.
• serverSide.js — Test helpers and scripts.

---

🚀 Getting Started

📋 Prerequisites

This project requires the following dependencies:

• Programming Language: JavaScript
• Package Manager: Npm

Recommended local prerequisites:

• Node.js (v14+ or v16+) — Runtime for the server and build tools.
• npm — Package manager used for installing dependencies and running scripts.
• MySQL (or compatible) — Database used for persistent storage of rooms, messages and questions.
• Git — Recommended for version control when cloning and contributing to the project.
• OpenSSL (optional) — Useful for generating local certs (e.g., ca.pem) if you test TLS locally.

Recommended versions & download links:

• Node.js (recommended v16+ LTS): https://nodejs.org/
• npm (bundled with Node.js): https://docs.npmjs.com/
• MySQL (recommended v8+): https://dev.mysql.com/downloads/mysql/
• Git: https://git-scm.com/
• OpenSSL (optional): https://www.openssl.org/

Quick install (examples)

macOS (Homebrew)

brew update
brew install node mysql git openssl
# Start MySQL (optional)
brew services start mysql

Windows (Chocolatey)

choco install nodejs-lts mysql git openssl -y
# After installing MySQL, run the MySQL installer or init steps as required

Debian / Ubuntu (apt — Node via NodeSource recommended)

sudo apt update
sudo apt install -y curl git mysql-server
# Install Node.js (example uses NodeSource for a modern Node LTS)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
# Secure MySQL (optional interactive step)
sudo mysql_secure_installation

⚙️ Installation

Clone the repository, install dependencies and configure the database connection.

git clone https://github.com/MA1002643/vevox-real-time-chat-web-application.git
cd vevox-real-time-chat-web-application/Vevox\ Chatroom
npm install
# Configure your MySQL connection (see README Prerequisites) before starting the servers.

💻 Usage

Start the application using the npm script. This will run the server(s) defined in package.json.

npm start

If the project uses separate scripts for the HTML server and WebSocket server, run the specific scripts (e.g. npm run start:html / npm run start:ws).

🧪 Testing

Automated tests use Mocha. Run the test suite with:

npm test

For a focused run, you can run individual test files with Mocha directly, e.g.: npx mocha test/serverSide.js.

---

🎓 Learning Outcomes

• Implemented real-time WebSocket communication from scratch.
• Gained practical experience in server–client synchronisation using ws.
• Strengthened understanding of asynchronous programming and event-driven architecture.
• Built and tested full-stack Node.js systems with MySQL integration.
• Applied modular software design principles for maintainability and scalability.

---

📈 Roadmap

• Task 1: Implement secure authentication system with JWT and user roles (user, moderator, admin).
• Task 2: Add real-time user presence, typing indicators, and message read receipts.
• Task 3: Integrate file and media uploads (images, documents) with cloud storage (e.g., AWS S3).
• Task 4: Implement message search, threaded replies, and emoji reactions for advanced chat interaction.
• Task 5: Add Redis Pub/Sub for scalable WebSocket message distribution across multiple instances.
• Task 6: Introduce database migrations and schema optimisation with Prisma or Knex.
• Task 7: Strengthen security and rate limiting using Helmet, CORS, and payload validation.
• Task 8: Expand testing coverage with integration, end-to-end (E2E), and performance tests.
• Task 9: Implement PWA features (offline mode, message queue, push notifications) for modern UX.
• Task 10: Add DevOps enhancements including Docker setup, CI/CD pipeline, and observability tools.

---

🤝 Contributors

---

✨ Acknowledgments

• Inspired by collaborative tools such as Vevox and Slack.
• Special thanks to contributors and Node.js open-source maintainers.
• Created as part of an academic exploration of real-time systems architecture.

---

📜 License

This project is licensed under the MIT License. See the LICENSE file for full details.

© 2025 Muhammad Abdullah
Developed with 💙 using Node.js & Express