Skip to content

Latest commit

 

History

History
827 lines (671 loc) · 19.4 KB

README.md

File metadata and controls

827 lines (671 loc) · 19.4 KB

Support Chat System 💬

Live Chat System for Customer Support

A comprehensive real-time support chat system built with Laravel, implementing clean architecture patterns including Repository Pattern and Service Layer. Supports authenticated users, guest visitors, and agent management.

🚀 Features

Core Functionality

  • Multi-User Support: Registered users and guest visitors
  • Real-time Messaging: Live chat functionality with WebSocket support
  • Agent Management: Automatic assignment and manual agent allocation
  • Session Management: Persistent chat sessions with unique identifiers
  • Message Types: Text, file uploads, and image sharing
  • Status Tracking: Read/unread message status and online indicators

Technical Features

  • Clean Architecture: Repository Pattern + Service Layer implementation
  • Comprehensive Testing: Unit and Feature tests with 85%+ coverage
  • API Documentation: RESTful API with detailed examples
  • Security: Role-based access control and input validation
  • Performance: Database optimization with proper indexing
  • Scalability: Queue system for background processing

📋 System Requirements

Server Requirements

  • PHP: >= 8.1
  • Laravel: >= 10.0
  • Database: MySQL >= 8.0 or PostgreSQL >= 13.0
  • Web Server: Apache 2.4+ or Nginx 1.18+
  • Memory: Minimum 512MB RAM (2GB+ recommended)

Development Tools

  • Composer: Latest version
  • Git: Latest version
  • Postman/Insomnia: For API testing

🔧 Installation & Setup

1. Clone Repository

git clone https://github.com/mustafaHgad/Chat-support.git
cd Chat-support

2. Install Dependencies

# Install PHP dependencies
composer install

3. Environment Configuration

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

# Configure your database in .env file:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=support_chat
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Configure mail settings for notifications:
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password

4. Database Setup

# Create database
mysql -u root -p
CREATE DATABASE support_chat CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
exit

# Run migrations and seeders
php artisan migrate:fresh --seed

# Install Sanctum for API authentication
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

5. Storage & Permissions

# Create storage link for file uploads
php artisan storage:link

# Set proper permissions (Linux/Mac)
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

# For Windows (run as administrator)
icacls storage /grant Users:F /T
icacls bootstrap/cache /grant Users:F /T

6. Queue Configuration (Optional)

# For real-time features and notifications
php artisan queue:table
php artisan migrate

# Start queue worker
php artisan queue:work --daemon

7. Start Development Server

php artisan serve
# Application available at: http://localhost:8000

🏗️ System Architecture

Architecture Overview

The system follows a layered architecture pattern with clear separation of concerns:

    ┌─────────────────┐    ┌─────────────────┐
    │   API Layer     │    │  Service Layer  │
    │   Controllers   │◄──►│   ChatService   │
    │   Middleware    │    │   MessageServ   │
    │   Validation    │    │                 │
    └─────────────────┘    └─────────────────┘
                                    │
                            ┌─────────────────┐
                            │ Repository Layer│
                            │   ChatRepo      │
                            │   MessageRepo   │
                            │   UserRepo      │
                            └─────────────────┘
                                      │
                            ┌─────────────────┐
                            │   Data Layer    │
                            │   MySQL/Postgres│
                            │   Redis Cache   │
                            │   File Storage  │
                            └─────────────────┘

Database Entity Relationship Diagram (ERD)

erDiagram
    USERS {
        bigint id PK
        varchar name
        varchar email UK
        varchar password
        enum role
        boolean is_online
        timestamp created_at
    }
    
    CHATS {
        bigint id PK
        varchar session_id UK
        bigint user_id FK
        bigint agent_id FK
        varchar guest_name
        varchar guest_email
        enum status
        timestamp started_at
        timestamp closed_at
    }
    
    MESSAGES {
        bigint id PK
        bigint chat_id FK
        bigint sender_id FK
        enum sender_type
        varchar sender_name
        text message
        enum message_type
        boolean is_read
        timestamp sent_at
    }
    
    USERS ||--o{ CHATS : "user_chats"
    USERS ||--o{ CHATS : "agent_chats"
    USERS ||--o{ MESSAGES : "user_messages"
    CHATS ||--o{ MESSAGES : "chat_messages"
Loading

📚 API Documentation

Base URL

Development: http://localhost:8000/api

Authentication

The API uses Laravel Sanctum for authentication. Include the token in the Authorization header:

Authorization: Bearer your-token-here

Endpoints Overview

Method Endpoint Description Auth Required
POST /auth/register Register new user No
POST /auth/login User login No
POST /auth/logout User logout Yes
GET /auth/user Get user profile Yes
POST /chat/start Start chat session Optional
GET /chat/{sessionId}/messages Get chat messages No
POST /messages/send Send message No
GET /agent/chats/waiting Get waiting chats Yes (Agent)
POST /agent/chats/{id}/assign Assign chat to agent Yes (Agent)
POST /agent/chats/{id}/close Close chat Yes (Agent)

API Usage Examples

1. User Registration

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmed Mohammed",
    "email": "ahmed@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "name": "Ahmed Mohammed",
      "email": "ahmed@example.com",
      "role": "user",
      "created_at": "2025-08-29T10:30:00.000000Z"
    },
    "token": "1|abc123def456ghi789..."
  },
  "message": "User registered successfully"
}

2. Start Chat Session (Guest)

curl -X POST http://localhost:8000/api/chat/start \
  -H "Content-Type: application/json" \
  -d '{
    "guest_name": "New Guest",
    "guest_email": "visitor@example.com"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "session_id": "chat_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "waiting",
    "guest_info": {
      "name": "New Guest",
      "email": "visitor@example.com"
    },
    "created_at": "2025-08-29T10:30:00.000000Z"
  },
  "message": "Chat session started successfully"
}

3. Send Message

curl -X POST http://localhost:8000/api/messages/send \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 1,
    "sender_type": "guest",
    "sender_name": "New Guest",
    "message": "Hi, I need help using the product.",
    "message_type": "text"
  }'

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "chat_id": 1,
    "sender": {
      "name": "New Guest",
      "type": "guest",
      "avatar": "https://ui-avatars.com/api/?name=New+Guest"
    },
    "message": "Hello, I need help using the product.",
    "message_type": "text",
    "is_read": false,
    "sent_at": "2025-08-29T10:35:00.000000Z"
  },
  "message": "Message sent successfully"
}

4. Get Chat Messages

curl -X GET http://localhost:8000/api/chat/chat_f47ac10b-58cc-4372-a567-0e02b2c3d479/messages \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "data": {
    "chat": {
      "id": 1,
      "session_id": "chat_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "active",
      "guest_info": {
        "name": "New Guest",
        "email": "visitor@example.com"
      },
      "messages_count": 3
    },
    "messages": [
      {
        "id": 1,
        "sender": {
          "name": "New Guest",
          "type": "guest"
        },
        "message": "Hello, I need help.",
        "sent_at": "2025-08-29T10:35:00.000000Z",
        "sent_at_human": "5 minutes ago"
      },
      {
        "id": 2,
        "sender": {
          "name": "Sarah Ahmed",
          "type": "agent"
        },
        "message": "Welcome! How can I help you?",
        "sent_at": "2025-08-29T10:37:00.000000Z",
        "sent_at_human": "3 minutes ago"
      }
    ]
  }
}

5. Agent Operations (Authentication Required)

# Get waiting chats
curl -X GET http://localhost:8000/api/agent/chats/waiting \
  -H "Authorization: Bearer agent-token-here" \
  -H "Content-Type: application/json"

# Assign chat to agent
curl -X POST http://localhost:8000/api/agent/chats/1/assign \
  -H "Authorization: Bearer agent-token-here" \
  -H "Content-Type: application/json"

# Close chat
curl -X POST http://localhost:8000/api/agent/chats/1/close \
  -H "Authorization: Bearer agent-token-here" \
  -H "Content-Type: application/json"

👥 How New Developers Can Contribute

Development Workflow

1. Fork & Clone

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/mustafaHgad/Chat-support.git
cd Chat-support

2. Set Up Development Environment

# Install dependencies
composer install

# Set up environment
cp .env.example .env
php artisan key:generate

# Set up database
php artisan migrate:fresh --seed

# Run tests to verify setup
php artisan test

3. Create Feature Branch

# Always work from develop branch
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/your-feature-name

# Examples:
git checkout -b feature/file-upload-support
git checkout -b feature/chat-transfer-functionality
git checkout -b feature/mobile-push-notifications

4. Development Guidelines

Code Standards:

  • Follow PSR-12 coding standards
  • Use meaningful variable and method names
  • Write PHPDoc comments for all public methods
  • Keep controllers thin (business logic in services)
  • Use Repository pattern for data access
  • Write tests for all new features

5. Testing Requirements

# Write tests for new features
php artisan make:test YourFeatureTest --feature
php artisan make:test YourServiceTest --unit

# Run tests before committing
php artisan test
php artisan test --coverage

# Ensure coverage > 80%
./vendor/bin/phpunit --coverage-html coverage-report

6. Commit Guidelines

# Commit message format:
type(scope): description

# Examples:
git commit -m "feat(chat): add file upload functionality"
git commit -m "fix(api): resolve validation error in message endpoint"
git commit -m "test(service): add unit tests for ChatService"
git commit -m "docs(readme): update API documentation"

7. Pull Request Process

# Push your feature branch
git push origin feature/your-feature-name

# Create Pull Request on GitHub:
# - Target: develop branch
# - Include: Description, testing notes, screenshots
# - Request review from Tech Lead
# - Ensure all tests pass

Branching Strategy

main (production)
├── develop (integration)
    ├── feature/file-upload-support
    ├── feature/chat-transfer
    ├── feature/push-notifications
    ├── feature/agent-dashboard
    ├── hotfix/critical-security-fix
    └── release/v1.1.0

Branch Descriptions:

  • main: Production-ready code only
  • develop: Integration branch for features
  • feature/*: Individual feature development
  • hotfix/*: Critical production fixes
  • release/*: Release preparation branches

🧪 Testing

Running Tests

# Run all tests
php artisan test

# Run specific test suites
php artisan test --testsuite=Unit
php artisan test --testsuite=Feature

# Run with coverage report
php artisan test --coverage
php artisan test --coverage-html coverage-report

# Run specific test class
php artisan test tests/Unit/Services/ChatServiceTest.php

# Run specific test method
php artisan test --filter test_send_message_successfully

Test Structure

tests/
├── Unit/                           # Unit Tests (85% coverage)
│   ├── Services/
│   │   ├── ChatServiceTest.php     # Business logic tests
│   │   └── MessageServiceTest.php  # Message handling tests
│   └── Repositories/
│       ├── ChatRepositoryTest.php  # Data access tests
│       └── MessageRepositoryTest.php
├── Feature/                        # Integration Tests
│   ├── ChatApiTest.php            # Chat endpoints
│   ├── MessageApiTest.php         # Message endpoints
│   ├── AuthenticationTest.php     # Auth system
│   ├── AgentFeaturesTest.php      # Agent functionality
│   └── RoleBasedAccessTest.php    # Security tests
└── TestCase.php                   # Base test class

Sample Test Data

// Test users created by seeders:
// Admin Agent: admin@example.com / admin123!@#
// Support Agent: support@example.com / support123
// Test Customer: ahmed.customer@example.com / password

🔐 Security

Authentication System

  • Laravel Sanctum: Token-based authentication
  • Role-based Access: User, Agent roles with specific permissions
  • Rate Limiting: 60 requests per minute for public endpoints
  • Input Validation: Comprehensive request validation
  • SQL Injection Protection: Eloquent ORM with parameter binding

Security Headers

// Implemented security headers:
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin

📊 Performance

Database Optimization

  • Indexes: Strategic indexing on frequently queried columns
  • Eager Loading: Prevents N+1 query problems
  • Query Optimization: Efficient joins and subqueries
  • Connection Pooling: Optimized database connections

Caching Strategy

// Implemented caching:
- User sessions: Redis
- Chat metadata: Application cache
- API responses: HTTP cache headers
- Database queries: Query result caching

Performance Benchmarks

  • API Response Time: < 200ms average
  • Database Queries: < 50ms for indexed queries
  • Memory Usage: < 128MB per request
  • Concurrent Users: 1000+ supported

🚀 Deployment

Production Deployment

# 1. Clone production code
git clone https://github.com/your-username/support-chat-system.git
cd support-chat-system
git checkout main

# 2. Install dependencies
composer install --optimize-autoloader --no-dev

# 3. Configure environment
cp .env.production .env

php artisan install:api
php artisan key:generate

# 4. Database setup
php artisan migrate --force
php artisan db:seed --class=ProductionSeeder

# 5. Optimize for production
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 6. Set up queue worker (systemd service)
php artisan queue:restart

Docker Deployment

FROM php:8.1-fpm

WORKDIR /var/www/html

# Install dependencies
COPY composer.json composer.lock ./
RUN composer install --optimize-autoloader --no-dev

# Copy application code
COPY . .

# Set permissions
RUN chown -R www-data:www-data storage bootstrap/cache

EXPOSE 8000
CMD ["php", "artisan", "serve", "--host=0.0.0.0"]

Environment Variables

# Production environment variables
APP_ENV=production
APP_DEBUG=false
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_HOST=prod-db-server
DB_DATABASE=support_chat_prod

# Cache & Session
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com

🛠️ Development Tools

Code Quality Tools

# Install development tools
composer require --dev phpstan/phpstan
composer require --dev squizlabs/php_codesniffer

# Run code analysis
./vendor/bin/phpstan analyse app/
./vendor/bin/phpcs --standard=PSR12 app/

# Fix code style automatically
./vendor/bin/phpcbf --standard=PSR12 app/
---

## 📈 Monitoring & Logging

### Application Logs
```bash
# View application logs
tail -f storage/logs/laravel.log

# View specific log levels
grep "ERROR" storage/logs/laravel.log
grep "INFO" storage/logs/laravel.log

Performance Monitoring

// Custom logging in services
Log::info('Chat created', [
    'chat_id' => $chat->id,
    'user_type' => $chat->user_id ? 'user' : 'guest',
    'response_time' => microtime(true) - $startTime
]);

🔧 Troubleshooting

Common Issues

Database Connection Error

# Check database service
sudo service mysql status
sudo service mysql start

# Test connection
mysql -u username -p -h localhost database_name

# Clear config cache
php artisan config:clear

Permission Issues

# Fix storage permissions
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

# Recreate storage link
php artisan storage:link

Composer Issues

# Clear composer cache
composer clear-cache
rm -rf vendor/
composer install

Queue Not Processing

# Restart queue workers
php artisan queue:restart

# Check failed jobs
php artisan queue:failed

# Process failed jobs
php artisan queue:retry all

Debug Mode

# Enable debug mode in .env
APP_DEBUG=true

# View detailed error messages
tail -f storage/logs/laravel.log

# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

📞 Support & Contact

Development Team

Documentation

  • API Documentation: /docs/api
  • Architecture Guide: /docs/architecture.md
  • Deployment Guide: /docs/deployment.md

📝 Changelog

Version 1.0.0 (2025-08-29)

  • ✅ Initial release
  • ✅ Basic chat functionality
  • ✅ User and agent management
  • ✅ Guest support
  • ✅ Real-time messaging
  • ✅ API documentation
  • ✅ Comprehensive testing

Planned Features (v1.1.0)

  • 🔄 File upload support
  • 🔄 Chat transfer between agents

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

  • Laravel Framework: For the excellent foundation

Built by Mustafa Hassan GadAllah

For technical questions or support, please create an issue on GitHub or contact our development team.