Real-Time Messaging System

A Laravel 11-based messaging platform featuring secure authentication, real-time communication via WebSockets, and persistent message history.

Features

• User Authentication: Secure registration and login powered by Laravel Breeze (Blade).
• Protected Access: Restricted functionality for authenticated users only.
• Member Directory: View a complete list of registered users upon login.
• Real-Time Chat: Instant messaging between users without page reloads.
• Message Persistence: All messages (sender, receiver, text, and timestamp) are stored in MySQL.
• Offline Message Sync: Users receive missed messages upon their next login.
• Event-Driven Architecture: Built using Laravel Events and Broadcasting.

Tech Stack

• Framework: Laravel 11.31+ (PHP 8.3+)
• Frontend: Blade Templates + Laravel Echo
• Database: MySQL 8+
• Broadcasting Server: Laravel Reverb
• Queue/Cache Store: Redis (via predis)
• Containerization: Laravel Sail (Docker)

---

Installation & Setup

Option 1: Using Laravel Sail (Docker)

This is the recommended way if you have Docker installed.

1. Clone the repository:

   git clone <repository-url>
   cd <project-folder>
   

2. Install PHP dependencies via Docker:

   docker run --rm \
   -u "$(id -u):$(id -g)" \
   -v "$(pwd):/var/www/html" \
   -w /var/www/html \
   laravelsail/php83-composer:latest \
   composer install --ignore-platform-reqs
   

3. Configure Environment:

   cp .env.example .env
   

4. Start the containers:

   ./vendor/bin/sail up -d
   

5. Initialize Application:

   ./vendor/bin/sail artisan key:generate
   ./vendor/bin/sail artisan migrate
   ./vendor/bin/sail npm install
   ./vendor/bin/sail npm run build
   

6. Initialize Reverb Broadcasting Server:

   ./vendor/bin/sail artisan reverb:start
   

7. Initialize queue worker

   ./vendor/bin/sail artisan queue:work
   

Option 2: Local Installation

1. Clone the repository:

    composer install
    npm install
   

2. Configure Environment:

   cp .env.example .env
   

3. Generate Application Key:

   php artisan key:generate
   php artisan migrate
   npm install
   npm run build
   

4. Start the server: To start all services (Web Server, WebSockets, Queues, and Vite) simultaneously:

   composer run dev
   

Database Schema

The core functionality relies on the following structure for the messages table:

Messages Table

Stores all communication history between users.

Field	Type	Description
id	BigInt (PK)	Unique message identifier.
sender_id	ForeignId	ID of the user who sent the message (refers to users.id).
receiver_id	ForeignId	ID of the user receiving the message (refers to users.id).
text	Text	The content of the message.
is_read	Boolean	Read status (default: false).
created_at	Timestamp	Date and time the message was created.
updated_at	Timestamp	Date and time of the last update.

---

Technical Implementation: Events & Broadcasting

The system uses a dedicated Event class MessageSent to handle real-time delivery.

1. Event Logic (App\Events\MessageSent)

When a message is sent, the event is dispatched with the following characteristics:

• ShouldBroadcast Interface: Tells Laravel to send this event to the broadcasting driver (Reverb via Redis) instead of just handling it locally.
• Eager Loading: The constructor automatically loads the sender relationship ($this->message->load('sender')), ensuring the recipient's UI can display who the message is from.
• Private Channel: It uses a secure PrivateChannel, named messenger.user.{receiver_id}. Only the intended recipient can listen to this channel.

2. Broadcasting Flow

1. Dispatch: The MessageSent event is triggered in the Controller after saving the message to MySQL.
2. Queue: The event is pushed to Redis (via the predis client).
3. Broadcast: Laravel Reverb picks up the event from Redis and broadcasts it to the specific WebSocket connection.
4. Frontend: Laravel Echo (on the client side) listens for the MessageSent event on the messenger.user.{id} channel and updates the chat UI in real-time.

Authentication & Getting Started

1. User Registration

You can create a new account manually by visiting: http://{host}/register

2. Quick Start with Demo Users (Seeding)

To quickly test the messaging system without manual registration, run the following command to populate the database with 5 pre-configured users:

# Using Sail
./vendor/bin/sail artisan migrate:fresh --seed
    
# Locally
php artisan migrate:fresh --seed

Test Credentials:

• alice@example.com
• bob@example.com
• charlie@example.com
• david@example.com
• eve@example.com
• Password: password (for all)

3. Login and Dashboard

After registration or seeding, navigate to: http://{host}/login

Once authenticated, you will see the Dashboard containing the list of all registered users. You can immediately start a real-time chat with any of them.

Real-Time UI & Notification Logic

The application provides a seamless experience for both active and returning users through dynamic UI updates.

1. Real-Time Notifications

• Global Alerts: When an authenticated user is anywhere on the dashboard or in another chat, new incoming messages trigger a popup notification in the top-right corner of the screen.
• Instant Chat Updates: If a user is currently in an active chat session with the sender, new messages appear instantly in the message bubble list without requiring a page reload.

2. Unread Message Badges

The system tracks the "read/unread" status of messages to ensure no communication is missed:

• Automatic Counting: If a user does not click on a popup notification or is not currently viewing that specific chat, the message remains "unread".
• Visual Indicators: A notification badge with a numeric counter appears next to the user's name in the contact list, showing the total number of unread messages from that specific person.
• Offline Synchronization: When a user logs in after being offline, the system automatically calculates unread messages from the database and displays the corresponding badges immediately.

3. State Management

• Marking as Read: Opening a chat with a specific user automatically updates the is_read status of their messages in the database and clears the UI badge.
• Live Sync: All badge updates and message deliveries are handled via Laravel Echo listening to the private messenger.user.{id} channel.