# Agent Module Technical Documentation

This document provides technical documentation for developers working with the Agent Module.

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Database Schema](#database-schema)
3. [Models and Relationships](#models-and-relationships)
4. [Controllers](#controllers)
5. [Vue Components](#vue-components)
6. [Routes](#routes)
7. [Services](#services)
8. [Progressive Web App](#progressive-web-app)
9. [Testing](#testing)

## Architecture Overview

The Agent Module follows the Laravel MVC architecture with the addition of Vue.js components for interactive features. The module is organized into several sub-modules:

- Training & Certification
- Marketing Tools
- Messaging & Communication
- Goals & Performance
- Reports & Analytics

Each sub-module has its own set of models, controllers, views, and Vue components.

## Database Schema

### Training & Certification

- `agent_training_materials`: Stores training materials
- `agent_training_progress`: Tracks agent progress on training materials
- `agent_certifications`: Stores certification information
- `agent_certification_requirements`: Links certifications to required training materials
- `agent_earned_certifications`: Tracks certifications earned by agents

### Marketing Tools

- `agent_marketing_materials`: Stores marketing materials
- `agent_marketing_usage`: Tracks usage of marketing materials
- `agent_landing_pages`: Stores landing page information
- `agent_landing_page_visits`: Tracks visits to landing pages
- `agent_landing_page_conversions`: Tracks conversions from landing pages

### Messaging & Communication

- `agent_messages`: Stores messages between agents and administrators
- `agent_announcements`: Stores announcements from administrators
- `agent_announcement_reads`: Tracks which announcements have been read by agents
- `agent_support_tickets`: Stores support tickets
- `agent_support_ticket_replies`: Stores replies to support tickets

### Goals & Performance

- `agent_goals`: Stores agent goals
- `agent_goal_progress`: Tracks progress towards goals

### Reports & Analytics

- `agent_custom_reports`: Stores custom report configurations
- `agent_report_exports`: Stores exported reports

## Models and Relationships

### Agent

```php
class Agent extends Model
{
    // Relationships
    public function user()
    {
        return $this->belongsTo(User::class);
    }
    
    public function trainingProgress()
    {
        return $this->hasMany(AgentTrainingProgress::class);
    }
    
    public function earnedCertifications()
    {
        return $this->hasMany(AgentEarnedCertification::class);
    }
    
    public function marketingUsage()
    {
        return $this->hasMany(AgentMarketingUsage::class);
    }
    
    public function landingPages()
    {
        return $this->hasMany(AgentLandingPage::class);
    }
    
    public function receivedMessages()
    {
        return $this->hasMany(AgentMessage::class, 'recipient_id', 'user_id');
    }
    
    public function sentMessages()
    {
        return $this->hasMany(AgentMessage::class, 'sender_id', 'user_id');
    }
    
    public function announcementReads()
    {
        return $this->hasMany(AgentAnnouncementRead::class);
    }
    
    public function supportTickets()
    {
        return $this->hasMany(AgentSupportTicket::class);
    }
    
    public function goals()
    {
        return $this->hasMany(AgentGoal::class);
    }
    
    public function customReports()
    {
        return $this->hasMany(AgentCustomReport::class);
    }
    
    public function reportExports()
    {
        return $this->hasMany(AgentReportExport::class);
    }
}
```

### Training & Certification Models

```php
class AgentTrainingMaterial extends Model
{
    // Relationships
    public function progress()
    {
        return $this->hasMany(AgentTrainingProgress::class, 'training_material_id');
    }
    
    public function certificationRequirements()
    {
        return $this->hasMany(AgentCertificationRequirement::class, 'training_material_id');
    }
}

class AgentTrainingProgress extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function trainingMaterial()
    {
        return $this->belongsTo(AgentTrainingMaterial::class, 'training_material_id');
    }
}

class AgentCertification extends Model
{
    // Relationships
    public function requirements()
    {
        return $this->hasMany(AgentCertificationRequirement::class, 'certification_id');
    }
    
    public function earnedCertifications()
    {
        return $this->hasMany(AgentEarnedCertification::class, 'certification_id');
    }
}

class AgentCertificationRequirement extends Model
{
    // Relationships
    public function certification()
    {
        return $this->belongsTo(AgentCertification::class, 'certification_id');
    }
    
    public function trainingMaterial()
    {
        return $this->belongsTo(AgentTrainingMaterial::class, 'training_material_id');
    }
}

class AgentEarnedCertification extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function certification()
    {
        return $this->belongsTo(AgentCertification::class, 'certification_id');
    }
}
```

### Marketing Tools Models

```php
class AgentMarketingMaterial extends Model
{
    // Relationships
    public function usage()
    {
        return $this->hasMany(AgentMarketingUsage::class, 'marketing_material_id');
    }
}

class AgentMarketingUsage extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function marketingMaterial()
    {
        return $this->belongsTo(AgentMarketingMaterial::class, 'marketing_material_id');
    }
}

class AgentLandingPage extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function visits()
    {
        return $this->hasMany(AgentLandingPageVisit::class, 'landing_page_id');
    }
    
    public function conversions()
    {
        return $this->hasMany(AgentLandingPageConversion::class, 'landing_page_id');
    }
}

class AgentLandingPageVisit extends Model
{
    // Relationships
    public function landingPage()
    {
        return $this->belongsTo(AgentLandingPage::class, 'landing_page_id');
    }
}

class AgentLandingPageConversion extends Model
{
    // Relationships
    public function landingPage()
    {
        return $this->belongsTo(AgentLandingPage::class, 'landing_page_id');
    }
}
```

### Messaging & Communication Models

```php
class AgentMessage extends Model
{
    // Relationships
    public function sender()
    {
        return $this->belongsTo(User::class, 'sender_id');
    }
    
    public function recipient()
    {
        return $this->belongsTo(User::class, 'recipient_id');
    }
}

class AgentAnnouncement extends Model
{
    // Relationships
    public function reads()
    {
        return $this->hasMany(AgentAnnouncementRead::class, 'announcement_id');
    }
}

class AgentAnnouncementRead extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function announcement()
    {
        return $this->belongsTo(AgentAnnouncement::class, 'announcement_id');
    }
}

class AgentSupportTicket extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function replies()
    {
        return $this->hasMany(AgentSupportTicketReply::class, 'ticket_id');
    }
}

class AgentSupportTicketReply extends Model
{
    // Relationships
    public function ticket()
    {
        return $this->belongsTo(AgentSupportTicket::class, 'ticket_id');
    }
    
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}
```

### Goals & Performance Models

```php
class AgentGoal extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
}
```

### Reports & Analytics Models

```php
class AgentCustomReport extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function exports()
    {
        return $this->hasMany(AgentReportExport::class, 'report_id');
    }
}

class AgentReportExport extends Model
{
    // Relationships
    public function agent()
    {
        return $this->belongsTo(Agent::class);
    }
    
    public function report()
    {
        return $this->belongsTo(AgentCustomReport::class, 'report_id');
    }
}
```

## Controllers

### Training & Certification Controllers

- `AgentTrainingController`: Handles training material display and progress tracking
- `AgentCertificationController`: Handles certification display and tracking

### Marketing Tools Controllers

- `AgentMarketingController`: Handles marketing material display and usage tracking
- `AgentLandingPageController`: Handles landing page creation, editing, and tracking

### Messaging & Communication Controllers

- `AgentMessageController`: Handles message sending, receiving, and management
- `AgentAnnouncementController`: Handles announcement display and tracking
- `AgentSupportController`: Handles support ticket creation, management, and replies

### Goals & Performance Controllers

- `AgentGoalController`: Handles goal creation, editing, and tracking

### Reports & Analytics Controllers

- `AgentReportController`: Handles custom report creation, editing, and generation

## Vue Components

### Training & Certification Components

- `TrainingQuiz.vue`: Interactive quiz component for training materials

### Marketing Tools Components

- `MarketingPerformanceChart.vue`: Chart component for marketing performance metrics
- `MarketingMaterialTabs.vue`: Tab component for organizing marketing materials
- `MarketingShareDropdown.vue`: Dropdown component for sharing marketing materials
- `LandingPageEditor.vue`: Editor component for creating and editing landing pages

### Goals & Performance Components

- `GoalProgressCard.vue`: Card component for displaying goal progress

### Reports & Analytics Components

- `ReportBuilder.vue`: Component for building custom reports

## Routes

### Training & Certification Routes

```php
Route::prefix('agent/training')->name('agent.training.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentTrainingController::class, 'index'])->name('dashboard');
    Route::get('/{material}', [AgentTrainingController::class, 'show'])->name('show');
    Route::post('/{material}/complete', [AgentTrainingController::class, 'complete'])->name('complete');
    Route::post('/{material}/quiz', [AgentTrainingController::class, 'submitQuiz'])->name('quiz');
    Route::get('/certifications', [AgentCertificationController::class, 'index'])->name('certifications');
    Route::get('/certifications/{certification}', [AgentCertificationController::class, 'show'])->name('certification.show');
});
```

### Marketing Tools Routes

```php
Route::prefix('agent/marketing')->name('agent.marketing.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentMarketingController::class, 'index'])->name('dashboard');
    Route::get('/library', [AgentMarketingController::class, 'library'])->name('library');
    Route::get('/materials/{material}', [AgentMarketingController::class, 'show'])->name('show');
    Route::get('/materials/{material}/download', [AgentMarketingController::class, 'download'])->name('download');
    Route::post('/materials/{material}/share', [AgentMarketingController::class, 'share'])->name('share');
    
    Route::get('/landing-pages', [AgentLandingPageController::class, 'index'])->name('landing-pages');
    Route::get('/landing-pages/create', [AgentLandingPageController::class, 'create'])->name('landing-pages.create');
    Route::post('/landing-pages', [AgentLandingPageController::class, 'store'])->name('landing-pages.store');
    Route::get('/landing-pages/{landingPage}/edit', [AgentLandingPageController::class, 'edit'])->name('landing-pages.edit');
    Route::put('/landing-pages/{landingPage}', [AgentLandingPageController::class, 'update'])->name('landing-pages.update');
    Route::delete('/landing-pages/{landingPage}', [AgentLandingPageController::class, 'destroy'])->name('landing-pages.delete');
});

// Public landing page routes
Route::get('/agent/{slug}', [AgentLandingPageController::class, 'show'])->name('agent.landing-page.show');
Route::post('/agent/{slug}/submit', [AgentLandingPageController::class, 'submit'])->name('agent.landing-page.submit');
Route::get('/agent/{slug}/thank-you', [AgentLandingPageController::class, 'thankYou'])->name('agent.landing-page.thank-you');
```

### Messaging & Communication Routes

```php
Route::prefix('agent/messages')->name('agent.messages.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentMessageController::class, 'inbox'])->name('inbox');
    Route::get('/sent', [AgentMessageController::class, 'sent'])->name('sent');
    Route::get('/compose', [AgentMessageController::class, 'compose'])->name('compose');
    Route::post('/', [AgentMessageController::class, 'send'])->name('send');
    Route::get('/{message}', [AgentMessageController::class, 'show'])->name('show');
    Route::post('/{message}/reply', [AgentMessageController::class, 'reply'])->name('reply');
    Route::delete('/{message}', [AgentMessageController::class, 'destroy'])->name('delete');
    Route::post('/read-all', [AgentMessageController::class, 'readAll'])->name('read-all');
});

Route::prefix('agent/announcements')->name('agent.announcements.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentAnnouncementController::class, 'index'])->name('index');
    Route::get('/{announcement}', [AgentAnnouncementController::class, 'show'])->name('show');
});

Route::prefix('agent/support')->name('agent.support.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentSupportController::class, 'index'])->name('index');
    Route::get('/create', [AgentSupportController::class, 'create'])->name('create');
    Route::post('/', [AgentSupportController::class, 'store'])->name('store');
    Route::get('/{ticket}', [AgentSupportController::class, 'show'])->name('show');
    Route::post('/{ticket}/reply', [AgentSupportController::class, 'reply'])->name('reply');
    Route::post('/{ticket}/close', [AgentSupportController::class, 'close'])->name('close');
    Route::post('/{ticket}/reopen', [AgentSupportController::class, 'reopen'])->name('reopen');
});
```

### Goals & Performance Routes

```php
Route::prefix('agent/goals')->name('agent.goals.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentGoalController::class, 'index'])->name('index');
    Route::get('/create', [AgentGoalController::class, 'create'])->name('create');
    Route::post('/', [AgentGoalController::class, 'store'])->name('store');
    Route::get('/{goal}', [AgentGoalController::class, 'show'])->name('show');
    Route::get('/{goal}/edit', [AgentGoalController::class, 'edit'])->name('edit');
    Route::put('/{goal}', [AgentGoalController::class, 'update'])->name('update');
    Route::delete('/{goal}', [AgentGoalController::class, 'destroy'])->name('delete');
});
```

### Reports & Analytics Routes

```php
Route::prefix('agent/reports')->name('agent.reports.')->middleware(['auth', 'role:agent'])->group(function () {
    Route::get('/', [AgentReportController::class, 'index'])->name('index');
    Route::get('/create', [AgentReportController::class, 'create'])->name('create');
    Route::post('/', [AgentReportController::class, 'store'])->name('store');
    Route::get('/{report}', [AgentReportController::class, 'show'])->name('show');
    Route::get('/{report}/edit', [AgentReportController::class, 'edit'])->name('edit');
    Route::put('/{report}', [AgentReportController::class, 'update'])->name('update');
    Route::delete('/{report}', [AgentReportController::class, 'destroy'])->name('delete');
    Route::post('/{report}/export', [AgentReportController::class, 'export'])->name('export');
    Route::get('/download/{export}', [AgentReportController::class, 'download'])->name('download');
});
```

## Services

### Training & Certification Services

- `TrainingService`: Handles training material logic
- `CertificationService`: Handles certification logic

### Marketing Tools Services

- `MarketingService`: Handles marketing material logic
- `LandingPageService`: Handles landing page logic

### Messaging & Communication Services

- `MessageService`: Handles message logic
- `AnnouncementService`: Handles announcement logic
- `SupportTicketService`: Handles support ticket logic

### Goals & Performance Services

- `GoalService`: Handles goal logic
- `PerformanceService`: Handles performance metrics logic

### Reports & Analytics Services

- `ReportService`: Handles report generation logic
- `ExportService`: Handles report export logic

## Progressive Web App

The Agent Module includes Progressive Web App (PWA) features for an enhanced mobile experience.

### Manifest

The PWA manifest is defined in `public/manifest.json` and includes:

- App name and description
- Icons
- Theme colors
- Start URL
- Display mode

### Service Worker

The service worker is defined in `public/service-worker.js` and includes:

- Caching strategies for assets
- Offline support
- Push notification handling

### Registration

The service worker is registered in `resources/js/service-worker-registration.js` and is imported in `resources/js/app.js`.

## Testing

The Agent Module includes comprehensive tests for all features.

### Feature Tests

- `AgentTrainingTest`: Tests for training and certification features
- `AgentMarketingTest`: Tests for marketing tools features
- `AgentMessagingTest`: Tests for messaging and communication features
- `AgentGoalsReportsTest`: Tests for goals, performance, and reporting features

### Model Factories

- `AgentTrainingMaterialFactory`: Factory for training materials
- `AgentCertificationFactory`: Factory for certifications
- `AgentMarketingMaterialFactory`: Factory for marketing materials
- `AgentLandingPageFactory`: Factory for landing pages
- `AgentMessageFactory`: Factory for messages
- `AgentAnnouncementFactory`: Factory for announcements
- `AgentSupportTicketFactory`: Factory for support tickets
- `AgentGoalFactory`: Factory for goals
- `AgentCustomReportFactory`: Factory for custom reports
- `AgentReportExportFactory`: Factory for report exports

### Database Seeder

The `AgentModuleSeeder` populates the database with test data for all Agent Module features.