VeloChat - Real-Time Chat Application

README.md Indonesia Ver.

Welcome to VeloChat! A modern, full-stack, real-time chat web application built from scratch with dedication by Ichramsyah Abdurrachman. This application is designed to provide a secure, fast, and intuitive communication experience.

🔥 Live Site: visit VeloChat in https://velochat.vercel.app

🔥 Live Route API: visit API VeloChat in https://velochat-backend-restful-apis-production.up.railway.app/

🎥 Video Demo: Watch the VeloChat demo video at https://youtube.com/demo-velochat

✨ Figma Design Link: View the Rinema design at https://www.figma.com/velochat-design

Table of Contents

• About VeloChat
• Key Features
• Technologies Used
• Deployment
• Database Structure
• Installation & Running the Project
• License
• Contributing
• Feature Contribution Ideas
• Contact

About VeloChat

VeloChat is an ambitious project to build a functional and feature-rich single-page application (SPA) for conversations. This project covers the entire development lifecycle, from designing a backend RESTful APIs architecture and real-time connections with Socket.IO to building a reactive and modern frontend interface using React JavaScript. The main focus is on security (JWT & Google OAuth authentication), user experience (real-time notifications, typing indicators, read receipts, responsive design), and clean, structured code quality.

Key Features ✅

The application is equipped with advanced features that make it a comprehensive communication platform:

Authentication & Security

• ✅ Manual registration with email domain validation (@gmail.com).
• ✅ Secure login system with hashed passwords.
• ✅ Third-party login & registration via Google OAuth 2.0.
• ✅ JWT (JSON Web Tokens)-based authorization to protect APIs.
• ✅ Protected pages accessible only after login.

Social & Friendship

• ✅ Search for other users by exact email.
• ✅ Friend Request System (Send, Accept, Decline).
• ✅ Real-time friend request notifications.
• ✅ Dynamic contact list separate from conversations.
• ✅ Contact list search with debounce feature.

Real-Time Chat Features

• ✅ Instant one-to-one messaging with Socket.IO.
• ✅ Permanent message history storage.
• ✅ Typing Indicator ("Typing...") when another user is typing.
• ✅ Unread Message Notifications with badge counts in the conversation list.
• ✅ Read Receipts with sent and seen checkmark icons.
• ✅ Timestamps and Date Separators (Today, Yesterday, etc.) for clear chat history.

Profile Management

• ✅ Ability to change profile name.
• ✅ Ability to update account password.
• ✅ Upload and change profile picture with storage on Cloudinary.
• ✅ Default profile picture for all new users.

Technologies Used

Category	Technologies
Frontend	React, Vite, Tailwind CSS, Zustand, React Router DOM, Axios, Socket.IO Client, @react-oauth/google, react-hot-toast, react-loading-skeleton, date-fns
Backend	Node.js, Express.js, Socket.IO, JSON Web Token (JWT), Passport.js (for Google OAuth), Mongoose, Bcrypt.js, Multer, Cloudinary, Express Session, Dotenv
Database	MongoDB Atlas (NoSQL)
Integrations	Google Cloud Platform (OAuth), Cloudinary (Media Storage)

Deployment

The application is deployed using modern CI/CD platforms:

• Frontend: https://velochat.vercel.app
• Backend: https://velochat-backend-restful-apis-production.up.railway.app/

Architecture

The VeloChat architecture is built on the MERN stack (MongoDB, Express.js, React, Node.js), utilizing Socket.IO for real-time bidirectional communication.

High-Level Overview

1. Client (Frontend): Built with React and Vite, it handles the UI and user interactions. It communicates with the backend via HTTP REST APIs (Axios) for standard operations (auth, profile updates) and Socket.IO for real-time chat features.
2. Server (Backend): An Express.js application that processes API requests, manages authentication (Passport.js/JWT), and handles WebSocket connections.
3. Database: MongoDB Atlas stores user data, chat history, and messages.
4. External Services:
   • Google OAuth: For secure third-party authentication.
   • Cloudinary: For storing profile pictures.

Architecture Diagram

graph TD
    User([User])
    Client["Frontend (React + Vite)"]
    Server["Backend (Node/Express)"]
    DB[("MongoDB Atlas")]
    Google[Google OAuth]
    Cloud[Cloudinary]

    User -- "HTTPS" --> Client
    Client -- "REST API (Axios)" --> Server
    Client -- "Real-time (Socket.IO)" --> Server
    Server <-->|Read/Write| DB
    Server -- "Auth Strategy" --> Google
    Server -- "Image Upload" --> Cloud

Loading

User Flow

graph TD
    Start([Start]) --> Login{Login / Register}
    Login -- "Success" --> Dashboard[Dashboard]
    Dashboard --> AddFriend[Add Friend]
    Dashboard --> SelectChat[Select Chat]
    AddFriend -- "Request Accepted" --> Chat[Chat Room]
    SelectChat --> Chat
    Chat --> SendMsg[Send Message]

Loading

Project Structure

The project is divided into two main directories:

• Frontend (/frontend): Contains the React application source code, public assets, and build configurations.
  • src/api: API integration logic.
  • src/components: Reusable UI components.
  • src/hooks: Custom React hooks.
  • src/layouts: Page layout definitions.
  • src/pages: Main application views/pages.
  • src/store: Zustand state management stores.
  • src/utils: Utility functions.
• Backend (/backend): Contains the API server logic.
  • config: Configuration files (e.g., DB connection).
  • controllers: Logic for handling requests.
  • middleware: Custom middleware (auth, error handling).
  • models: Mongoose schemas for MongoDB.
  • routes: API route definitions.

Database Structure

The application uses four main models in MongoDB to structure data:

• User:
  • name: User's name.
  • email: Unique email (as identifier).
  • password: Hashed password.
  • profilePic: URL to profile picture.
  • contacts: Array of other users' IDs who are friends.
• Chat:
  • users: Array of user IDs in the conversation.
  • latestMessage: Reference to the latest message for sidebar preview.
  • isGroupChat: Boolean indicating if it’s a group chat.
• Message:
  • sender: ID of the user who sent the message.
  • content: Message content (text or encrypted data).
  • chat: ID of the chat where the message belongs.
  • readBy: Array of user IDs who have read the message.
• FriendRequest:
  • fromUser: ID of the user sending the request.
  • toUser: ID of the user receiving the request.
  • status: Request status ('pending', 'accepted', 'declined').

Installation & Running the Project

Prerequisites:

• Node.js (v18 or higher)
• NPM (Node Package Manager)
• MongoDB Atlas account
• Google Cloud Platform account (for OAuth credentials)
• Cloudinary account (for image storage)

Steps:

1. Clone the Repository

   git clone https://github.com/ichramsyah/velochat-fullstack-webApp.git
   cd velochat-fullstack-webApp

2. Set Up the Backend

   cd backend
   npm install

   Create a .env file in the /backend folder and add all required environment variables (see "Technologies" section).

   Run the backend server:

   npm run dev

3. Set Up the Frontend

   Open a new terminal and, from the project root directory (/velochat), run:

   cd frontend
   npm install

   Create a .env file in the /frontend folder and add:

   VITE_GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
   

   Run the frontend server:

   npm run dev

4. Run via Docker (Optional)

   If you prefer to run the entire application using Docker:

   1. Ensure you have Docker and Docker Compose installed.

   2. Create .env files in both /backend and /frontend directories.

   3. Run the following command from the root directory:

      docker-compose up --build

   The application will be accessible at http://localhost:3000.

5. Access the Application

   • Open http://localhost:5173 (Local) or http://localhost:3000 (Docker) in your browser.

License

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

Contributing

Contributions are warmly welcomed! If you’d like to contribute to this project, please fork the repository and create a pull request with your proposed changes.

1. Fork the Project
2. Create Your Feature Branch (git checkout -b feature/YourNewFeature)
3. Commit Your Changes (git commit -m 'Add YourNewFeature')
4. Push to the Branch (git push origin feature/YourNewFeature)
5. Open a Pull Request

Please adhere to our Code of Conduct and ensure your contributions align with VeloChat’s mission for constructive and respectful discussions.

Feature Contribution Ideas

Some ideas for future features to add:

• Group Chat: Full functionality for creating and managing group chats.
• File Sharing: Sending files beyond images (PDF, DOCX, etc.).
• Online/Offline Status: Displaying user online status indicators.
• Message Search: Feature to search messages within a conversation.
• Emoji Picker: Adding an emoji selection option to the message input.

Contact

Ichramsyah Abdurrachman - ichramsyahabdurrachman@gmail.com

Project Link: https://github.com/ichramsyah/velochat-fullstack-webApp.git