# Laravel Upsideads - Lead Management System

A powerful Laravel-based lead management and distribution system with automated scheduling, multi-lead routing, and comprehensive admin controls. This application handles lead queue management, affiliate network management, and lead delivery to multiple clients with configurable delays.

## 📋 Table of Contents

- [Project Overview](#project-overview)
- [Technology Stack](#technology-stack)
- [System Requirements](#system-requirements)
- [Project Structure](#project-structure)
- [Installation & Setup](#installation--setup)
- [Environment Configuration](#environment-configuration)
- [Database Setup](#database-setup)
- [Scheduled Tasks & Cron Jobs](#scheduled-tasks--cron-jobs)
- [Running the Application](#running-the-application)
- [API Documentation](#api-documentation)
- [Features](#features)
- [Commands](#commands)
- [Troubleshooting](#troubleshooting)

## 🎯 Project Overview

This is a comprehensive lead management platform built with Laravel 10, featuring:

- **Lead Distribution**: Intelligent lead queuing and distribution system
- **Delayed Delivery**: Support for delayed lead delivery to clients
- **Multi-Client Support**: Route leads to multiple clients based on rules
- **Admin Dashboard**: Complete control over leads, clients, and affiliates
- **API-First Architecture**: RESTful API for all operations
- **Automated Scheduling**: Laravel Scheduler for background tasks
- **Real-time Lead Processing**: Automated lead sending with configurable cycles

## 🛠 Technology Stack

### Backend
- **Framework**: Laravel 10.10+
- **Language**: PHP 8.1+
- **Database**: MySQL/MariaDB
- **Authentication**: Laravel Passport (OAuth 2.0)
- **Job Queue**: Database-based (configurable)

### Frontend
- **Framework**: Vue.js
- **Build Tool**: Webpack
- **Package Manager**: npm

### Additional Packages
- **Excel Export/Import**: Maatwebsite Excel 3.1+
- **PDF Generation**: Laravel DOMPDF 2.0+
- **CSV Handling**: League CSV 9.11+
- **API Documentation**: Scribe 4.29+

## 📦 System Requirements

### Server Requirements
- **PHP**: 8.1 or higher
- **Composer**: Latest version
- **Node.js**: 14+ (for frontend assets)
- **npm**: 6+ (for frontend dependencies)
- **MySQL/MariaDB**: 5.7.8+
- **OpenSSL PHP Extension**: Required
- **PDO PHP Extension**: Required
- **Mbstring PHP Extension**: Required
- **Tokenizer PHP Extension**: Required
- **XML PHP Extension**: Required
- **JSON PHP Extension**: Required

### For Cron Jobs
- Unix/Linux server with cron daemon
- SSH access or hosting control panel
- Ability to set up cron jobs

## 📁 Project Structure

### Backend (Laravel)

```
app/
├── Console/
│   ├── Commands/
│   │   ├── SendLeadCycleLeads.php      # Send leads for LeadCycle clients
│   │   ├── SendDelayedLeads.php         # Send delayed leads from queue
│   │   ├── SendMultiDelayedLeads.php    # Send multi-lead delayed leads
│   │   ├── UpdateSentPerDay.php         # Update daily send limits
│   │   └── RotateLogs.php               # Rotate application logs
│   └── Kernel.php                       # Console kernel & scheduling
├── Http/
│   ├── Controllers/
│   │   └── Api/V1/
│   │       ├── AdminUser/               # Admin-specific controllers
│   │       │   ├── LeadController.php
│   │       │   └── OfferController.php
│   │       └── Common/
│   │           └── Auth/                # Authentication controllers
│   ├── Middleware/                      # HTTP middleware
│   ├── Requests/                        # Form requests & validation
│   └── Resources/                       # API resources
├── Models/                              # Eloquent models
│   ├── Offer.php
│   ├── OfferAffiliate.php
│   ├── OfferLead.php
│   ├── LeadQueue.php
│   ├── User.php
│   └── ...other models
├── Repositories/                        # Repository pattern
│   ├── BaseRepository.php
│   ├── Offer/OfferRepository.php
│   ├── OfferLead/OfferLeadRepository.php
│   └── ...other repositories
├── Services/                            # Business logic
│   ├── LeadService.php
│   ├── ClientManager.php
│   ├── Clients/                         # Client integrations
│   └── ...other services
├── Jobs/                                # Queued jobs
│   ├── SendLeadJob.php
│   └── ReminderEmails.php
├── Mail/                                # Mailable classes
├── Exports/                             # Excel exports
│   ├── CustomerInvoiceExport.php
│   └── ...other exports
└── helpers.php                          # Helper functions

config/                                  # Configuration files
├── app.php
├── database.php
├── queue.php
├── mail.php
├── cache.php
└── ...other configs

database/
├── migrations/                          # Database migrations
├── seeders/                             # Database seeders
└── factories/                           # Model factories

routes/
├── api.php                              # API routes
├── web.php                              # Web routes
├── console.php                          # Console routes
└── modules/                             # Modular routes

resources/
├── views/                               # Blade templates
└── js/                                  # Vue.js components

storage/
├── logs/                                # Application logs
├── app/                                 # Temporary files
└── framework/                           # Framework cache

public/                                  # Web root
├── index.php
├── media/                               # Static media files
└── img/                                 # Images and SVGs
```

## 🚀 Installation & Setup

### Step 1: Clone the Repository

```bash
git clone <repository-url>
cd laravel-upsideads
```

### Step 2: Install PHP Dependencies

```bash
composer install
```

This will install all required PHP packages including:
- Laravel Framework
- Laravel Passport
- Maatwebsite Excel
- DOMPDF
- Scribe API Documentation

### Step 3: Create Environment File

```bash
cp .env.example .env
```

### Step 4: Generate Application Key

```bash
php artisan key:generate
```

### Step 5: Install Node Dependencies (Frontend)

```bash
npm install
```

### Step 6: Build Frontend Assets

**Development:**
```bash
npm run dev
```

**Production:**
```bash
npm run build
```

### Step 7: Run Database Migrations

```bash
php artisan migrate
```

Or use the provided deployment script:

```bash
chmod +x deploy.sh
./deploy.sh
```

### Step 8: Generate Passport Keys (OAuth 2.0)

```bash
php artisan passport:keys
```

If using the deploy script, this is handled automatically.

### Step 9: Generate API Documentation

```bash
php artisan scribe:generate
```

### Step 10: Set File Permissions (Linux/Unix)

```bash
chmod -R 775 storage bootstrap/cache
chmod -R 755 public
```

### Step 11: Start Development Server

```bash
php artisan serve
```

The application will be available at `http://localhost:8000`

---

## ⚙️ Environment Configuration

Create or update your `.env` file with the following critical settings:

```env
APP_NAME="Upsideads"
APP_ENV=production
APP_KEY=base64:xxxxx (generated by key:generate)
APP_DEBUG=false
APP_URL=https://your-domain.com

# Database Configuration
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_upsideads
DB_USERNAME=root
DB_PASSWORD=your_password

# Cache Configuration
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=database

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=465
MAIL_USERNAME=your_email
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com
MAIL_FROM_NAME="Upsideads"

# Redis Configuration (for caching/queue)
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Passport Configuration
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=xxxxx
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=xxxxx

# Application Settings
LOG_CHANNEL=stack
LOG_LEVEL=debug
```

### Important Environment Variables Explained

| Variable | Description |
|----------|-------------|
| `APP_ENV` | Set to `production` on live servers, `local` for development |
| `APP_DEBUG` | Set to `false` in production |
| `DB_CONNECTION` | Database driver (mysql, postgresql, etc.) |
| `QUEUE_CONNECTION` | Queue driver (database, redis, sync) |
| `CACHE_DRIVER` | Caching driver (redis, memcached, database, file) |
| `MAIL_DRIVER` | Mail driver (smtp, mailgun, sendgrid, etc.) |

---

## 🗄️ Database Setup

### Create Database

```bash
mysql -u root -p -e "CREATE DATABASE laravel_upsideads CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

### Run Migrations

```bash
php artisan migrate
```

### Run Seeders (Optional)

```bash
php artisan db:seed
```

### Create Admin User

```bash
php artisan tinker
```

Then in the tinker shell:

```php
App\Models\User::create([
    'name' => 'Admin',
    'email' => 'admin@example.com',
    'password' => Hash::make('password'),
    'role_id' => 1,
]);
```

### Database Tables Overview

Key tables created by migrations:

- `users` - Application users
- `leads` - Lead records
- `lead_queue` - Queued leads for delivery
- `offers` - Offers/Products
- `offer_affiliates` - Affiliate associations
- `offer_leads` - Lead-Offer associations
- `api_logs` - API request logs
- `migrations` - Migration history

---

## ⏰ Scheduled Tasks & Cron Jobs

### Overview of Scheduled Commands

The application includes automated tasks managed through Laravel's Task Scheduler. All commands run **every minute** to ensure real-time lead processing:

#### Scheduled Commands

1. **`leads:send-cycle`** (Every Minute)
   - Sends delayed leads for LeadCycle SMS clients
   - Processes leads waiting in the queue
   - Handles multi-client delivery
   - Memory limit: 1024MB

2. **`leads:send-multi-delayed`** (Every Minute)
   - Handles multi-lead delayed delivery system
   - Processes leads from `LeadQueue` model
   - Removes processed leads from queue
   - Uses LeadService for delivery

3. **`leads:send-delayed`** (Every Minute)
   - Sends standard delayed leads
   - Cleans up queue after successful delivery
   - Calls PostLead controller logic

4. **`leads:update-sent-per-day`** (Every Minute)
   - Updates daily send limits per client/affiliate
   - Maintains capping thresholds
   - Prevents over-sending to clients

5. **`logs:rotate`** (Every Hour)
   - Rotates application logs
   - Archives logs when they exceed 5MB
   - Names archived logs with timestamp

### Schedule Configuration

Located in: `app/Console/Kernel.php`

```php
protected function schedule(Schedule $schedule): void
{
    $schedule->command('logs:rotate')->hourly();
    $schedule->command('leads:send-cycle')->everyMinute();
    $schedule->command('leads:send-multi-delayed')->everyMinute();
    $schedule->command('leads:send-delayed')->everyMinute();
    $schedule->command('leads:update-sent-per-day')->everyMinute();
}
```

### Setting Up Cron on Your Server

The Laravel Task Scheduler requires a single cron job that runs the scheduler every minute.

#### ✅ Step 1: Edit Crontab

SSH into your server and open crontab:

```bash
crontab -e
```

#### ✅ Step 2: Add the Scheduler Cron Job

Add this single line to your crontab:

```bash
* * * * * cd /path/to/laravel-upsideads && php artisan schedule:run >> /dev/null 2>&1
```

**Replace `/path/to/laravel-upsideads` with your actual project path.**

#### ✅ Step 3: Verify the Path

Find your Laravel project path:

```bash
pwd
# Output: /home/username/public_html/laravel-upsideads
```

Example for common hosting setups:

**cPanel/Shared Hosting:**
```bash
* * * * * cd /home/yourusername/public_html/laravel-upsideads && php artisan schedule:run >> /dev/null 2>&1
```

**VPS (Ubuntu/Debian):**
```bash
* * * * * cd /var/www/laravel-upsideads && php artisan schedule:run >> /dev/null 2>&1
```

**Docker Container:**
```bash
* * * * * cd /app && php artisan schedule:run >> /dev/null 2>&1
```

#### ✅ Step 4: Save and Exit

- **Nano editor**: Press `Ctrl + X`, then `Y`, then `Enter`
- **Vim editor**: Press `Esc`, type `:wq`, then `Enter`

#### ✅ Step 5: Verify Cron Installation

```bash
crontab -l
```

You should see your entry listed.

### ⚠️ Important: Single Cron Entry

**Do NOT add multiple entries for each command!** The single `schedule:run` entry triggers all scheduled commands internally. Multiple entries will cause duplicate task execution.

### Alternative: Queue-Based Processing

If you prefer, you can use Laravel's queue system instead of the scheduler:

#### Set Queue Driver

Update your `.env` file:

```env
QUEUE_CONNECTION=database
# or use Redis: QUEUE_CONNECTION=redis
```

#### Create Jobs

Create queue jobs instead of scheduled commands:

```bash
php artisan make:job SendLeadJob
```

#### Process Queue

Run the queue worker:

```bash
php artisan queue:work database --sleep=3 --tries=3
```

Or add to crontab:

```bash
* * * * * cd /path/to/app && php artisan queue:work --once >> /dev/null 2>&1
```

### Monitoring Scheduler

#### View Scheduled Tasks

```bash
php artisan schedule:list
```

#### Test Run a Command

```bash
php artisan leads:send-cycle
php artisan leads:send-multi-delayed
php artisan leads:send-delayed
php artisan leads:update-sent-per-day
```

#### View Application Logs

```bash
tail -f storage/logs/laravel.log
```

#### Check Cron Execution

```bash
# View recent cron jobs
sudo grep CRON /var/log/syslog | tail -20

# On Ubuntu 18.04+
sudo journalctl -u cron --since "1 hour ago"
```

### Cron Configuration Checklist

- [ ] SSH access to server confirmed
- [ ] Correct project path identified
- [ ] Cron entry added to crontab
- [ ] Crontab saved successfully
- [ ] Cron is enabled (`sudo systemctl status cron`)
- [ ] PHP CLI path is correct
- [ ] Database credentials in `.env` are correct
- [ ] Log file permissions allow writing
- [ ] Tested with `php artisan schedule:work` (interactive mode)

---

## 🏃 Running the Application

### Development Environment

```bash
# Terminal 1: Start Laravel development server
php artisan serve

# Terminal 2: Build frontend assets in watch mode
npm run watch
```

The application will be available at `http://localhost:8000`

### Production Environment

#### Using PHP Built-in Server (Not Recommended)

```bash
php artisan serve --host=0.0.0.0 --port=8000
```

#### Using Apache

1. Update DocumentRoot in VirtualHost to point to `/public` directory
2. Enable mod_rewrite
3. Set proper permissions
4. Restart Apache

#### Using Nginx

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/laravel-upsideads/public;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}
```

#### Using Docker

```dockerfile
FROM php:8.1-fpm
# ... additional setup
CMD ["php", "artisan", "serve", "--host=0.0.0.0"]
```

### Performance Optimization (Production)

```bash
# Optimize autoloader
composer install --optimize-autoloader --no-dev

# Cache Laravel configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize
php artisan optimize
```

---

## 📚 API Documentation

### Authentication Endpoints

#### Login

```http
POST /api/v1/auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password"
}
```

**Response:**
```json
{
    "access_token": "token_string",
    "token_type": "Bearer",
    "expires_in": 31536000
}
```

#### Register

```http
POST /api/v1/auth/register
Content-Type: application/json

{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password",
    "password_confirmation": "password"
}
```

#### Forgot Password

```http
POST /api/v1/auth/forgot-password
Content-Type: application/json

{
    "email": "user@example.com"
}
```

#### Reset Password

```http
POST /api/v1/auth/reset-password
Content-Type: application/json

{
    "email": "user@example.com",
    "token": "reset_token",
    "password": "new_password",
    "password_confirmation": "new_password"
}
```

#### Change Password (Authenticated)

```http
POST /api/v1/auth/change-password
Authorization: Bearer {access_token}
Content-Type: application/json

{
    "current_password": "old_password",
    "password": "new_password",
    "password_confirmation": "new_password"
}
```

### Generate API Documentation

```bash
php artisan scribe:generate
```

This generates comprehensive API documentation in `public/docs`

---

## ✨ Features

### Lead Management
- ✅ Lead creation and tracking
- ✅ Queue management with delays
- ✅ Multi-client lead distribution
- ✅ Real-time lead status tracking
- ✅ Lead response logging
- ✅ Unsubscribe management

### Client Management
- ✅ Multiple client support
- ✅ Client affiliate management
- ✅ Per-client configuration
- ✅ Daily send limits (capping)
- ✅ Domain filtering
- ✅ Client-specific workflows

### Offer Management
- ✅ Offer creation and management
- ✅ Affiliate commission tracking
- ✅ Offer performance analytics
- ✅ Multi-affiliate support

### Automated Scheduling
- ✅ Minute-based lead processing
- ✅ Delayed delivery system
- ✅ Cycle-based lead sending
- ✅ Automatic log rotation
- ✅ Daily limit updates

### Reporting & Export
- ✅ Lead export (Excel, CSV)
- ✅ Invoice generation
- ✅ Payment reconciliation
- ✅ Performance analytics
- ✅ Custom report filters

### Security
- ✅ OAuth 2.0 Authentication (Passport)
- ✅ Role-based access control
- ✅ API logging
- ✅ Request validation
- ✅ CORS support
- ✅ Password hashing

---

## 📋 Commands

### Artisan Commands

```bash
# Serve application
php artisan serve

# Run migrations
php artisan migrate
php artisan migrate:fresh
php artisan migrate:rollback

# Create models, controllers, etc.
php artisan make:controller ControllerName
php artisan make:model ModelName
php artisan make:migration migration_name

# Cache commands
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize

# Queue commands
php artisan queue:work
php artisan queue:retry all
php artisan queue:flush

# Database seeders
php artisan db:seed
php artisan db:seed --class=UserSeeder

# Tinker (Interactive shell)
php artisan tinker

# Authentication
php artisan passport:install
php artisan passport:keys

# Scheduling
php artisan schedule:run
php artisan schedule:work
php artisan schedule:list
php artisan schedule:test

# Custom Commands
php artisan leads:send-cycle
php artisan leads:send-multi-delayed
php artisan leads:send-delayed
php artisan leads:update-sent-per-day
php artisan logs:rotate

# API Documentation
php artisan scribe:generate
```

### NPM Commands

```bash
# Install dependencies
npm install

# Development mode
npm run dev

# Watch for changes
npm run watch

# Production build
npm run build

# Linting
npm run lint
```

---

## 🐛 Troubleshooting

### Common Issues

#### 1. Composer Error: "Package not found"

```bash
composer clear-cache
composer install
```

#### 2. Database Connection Error

- Verify `.env` database credentials
- Ensure MySQL service is running
- Check database exists

```bash
mysql -u root -p -e "SHOW DATABASES;"
```

#### 3. Cron Not Running

**Check cron status:**
```bash
sudo systemctl status cron
```

**Check cron logs:**
```bash
sudo tail -f /var/log/syslog | grep CRON
```

**Test schedule manually:**
```bash
php artisan schedule:work
```

#### 4. Permissions Error

```bash
chmod -R 775 storage bootstrap/cache
chmod -R 755 public
chown -R www-data:www-data storage bootstrap/cache
```

#### 5. Queue Jobs Not Processing

```bash
# Check queue status
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all

# Clear queue
php artisan queue:flush

# Check database connection
php artisan tinker
# Then: DB::connection()->getPdo();
```

#### 6. Passport Not Working

```bash
php artisan passport:install
php artisan passport:keys
```

#### 7. 503 Service Unavailable

Check Laravel logs:
```bash
tail -f storage/logs/laravel.log
```

Common causes:
- Permissions issues
- Missing environment variables
- Database connection failure
- Out of disk space

#### 8. Scheduled Tasks Not Running

```bash
# Verify cron entry
crontab -l

# Test schedule
php artisan schedule:list
php artisan schedule:work

# Check log output
tail -f storage/logs/laravel.log

# Manual test
php artisan leads:send-cycle
```

### Getting Help

1. Check Laravel logs: `storage/logs/laravel.log`
2. Enable debug mode: Set `APP_DEBUG=true` in `.env` (development only)
3. Run: `php artisan tinker` for interactive debugging
4. Check error messages carefully

---

## 📞 Support & Maintenance

### Regular Maintenance Tasks

#### Daily
- Monitor application logs
- Check queue status
- Verify cron execution

#### Weekly
- Review failed jobs
- Check server disk space
- Review API logs

#### Monthly
- Update dependencies: `composer update`
- Review and optimize database queries
- Backup database
- Check SSL certificate expiration

### Backup Strategy

```bash
# Backup database
mysqldump -u root -p laravel_upsideads > backup.sql

# Backup application
tar -czf laravel-backup.tar.gz /path/to/app

# Restore database
mysql -u root -p laravel_upsideads < backup.sql
```

---

## 📄 License

This project is licensed under the MIT License.

---

## 👥 Contributing

When extending functionality:
- Follow Laravel best practices
- Use repository pattern for database access
- Add appropriate validation
- Include error logging
- Write tests for new features
- Document changes in README

---

## 🚀 Deployment Checklist

- [ ] Clone repository
- [ ] Install dependencies (`composer install`)
- [ ] Set up `.env` file with production values
- [ ] Generate application key
- [ ] Run migrations
- [ ] Generate Passport keys
- [ ] Set proper file permissions
- [ ] Configure web server (Apache/Nginx)
- [ ] Set up SSL certificate
- [ ] Configure email (SMTP)
- [ ] Set up cron job for scheduler
- [ ] Enable proper logging
- [ ] Test all API endpoints
- [ ] Test scheduled tasks
- [ ] Set up monitoring/alerts
- [ ] Configure backups
- [ ] Test disaster recovery

---

**Last Updated**: November 2025  
**Version**: 1.0.0  
**Laravel Version**: 10.10+  
**PHP Version**: 8.1+