# CC System Refactoring & Upgrade Documentation

## Executive Summary

This document provides a comprehensive analysis of the current CC System architecture and a detailed roadmap for refactoring the software to remove FreePBX dependencies and upgrade to newer versions of Laravel and associated technologies.

**Current System:** Laravel 8/9 + MySQL/MariaDB + Asterisk + FreePBX + Custom Telephony Modules
**Target System:** Laravel 11/12 + MySQL/MariaDB + Direct Asterisk Integration + Enhanced Custom Telephony Features managed directly through the new version of the software 

## Current System Architecture Analysis

### 1. Core Laravel Application Structure

#### Framework & Dependencies
- **Laravel Version:** 8.x/9.x (based on composer.json)
- **PHP Version:** >=7.3.0
- **Database:** MySQL/MariaDB with multiple database connections
- **Key Dependencies:**
  - `marcelog/pami` & `marcelog/pagi` - Asterisk Manager Interface
  - `nwidart/laravel-modules` - Modular architecture
  - `spatie/laravel-permission` - Role-based access control
  - `torzer/awesome-landlord` - Multi-tenancy support

#### Module Architecture
The system uses a comprehensive modular structure with the following core modules:

**Business Logic Modules:**
- **Accounts** - Customer/company management
- **Contacts** - Individual contact management  
- **Leads** - Lead generation and tracking
- **Campaigns** - Marketing campaign management
- **Calls** - Call logging and management
- **Deals** - Sales opportunity tracking
- **Invoices/Orders/Quotes** - Financial transactions
- **Tickets** - Support ticket system
- **SMS** - SMS messaging integration
- **Calendar** - Event and scheduling management

**Supporting Modules:**
- **Platform** - Core platform functionality, users, companies
- **Assets** - Asset management
- **Documents** - Document management with attachments
- **Payments** - Payment processing
- **Reporting** - Analytics and reports
- **Vendors** - Vendor relationship management

### 2. FreePBX Integration Points (Current State)

#### Configuration Files
FreePBX integration is primarily managed through Asterisk configuration files located in `/pbx-dialplan/asterisk/`:

**Auto-Generated FreePBX Files:**
- `extensions.conf` - Main dialplan (FreePBX generated)
- `extensions_additional.conf` - FreePBX additional extensions
- `extensions_custom.conf` - Custom dialplan modifications
- `manager.conf` - AMI configuration
- `sip.conf` / `pjsip.conf` - SIP channel configurations
- `queues.conf` - Queue configurations
- Various FreePBX-specific config files (marked with "auto-generated by FreePBX")

**Custom Integration Points:**
- `/routes/console.php` - Contains FreePBX symlink creation: `ln -s /var/www/html/.freepbx-known/`
- `/dialplan/extensions_custom.conf` - Custom dialplan extensions
- AGI script integration through Laravel Artisan commands

#### Data Flow Dependencies
1. **CDR Processing:** `App\CDR` model connects to `asteriskcdrdb.cdr` table
2. **Event Handling:** `App\AsteriskEventsHandler` processes AMI events
3. **Extension Management:** FreePBX manages extension configurations
4. **Dialplan Logic:** Mix of FreePBX auto-generated and custom dialplan

### 3. Direct Asterisk Integration (Current)

#### AMI (Asterisk Manager Interface)
- **Primary Handler:** `App\AsteriskEventsHandler` implements `IEventListener`
- **Event Processing:** Real-time event handling for:
  - Peer status changes (extension registration/unregistration)
  - Call events and state changes
  - Queue events and statistics
- **AMI Actions Supported:** Extensive list including:
  - Call origination (`OriginateAction`)
  - Call control (hangup, transfer, bridge)
  - SIP peer management
  - Queue management
  - Database operations (DBGet, DBPut)

#### AGI (Asterisk Gateway Interface)  
- **Implementation:** Laravel Artisan commands serve as AGI scripts
- **Key AGI Handlers:**
  - `agihangupaction` - Call disposition and logging
  - `agi:handler` - General AGI processing
- **Call Flow Integration:** Handles call routing, logging, and post-call processing

#### CDR (Call Detail Records)
- **Model:** `App\CDR` 
- **Database:** Separate `asteriskcdrdb.cdr` table
- **Integration:** Direct database connection for call analytics and reporting

### 4. Database Schema & Relationships

#### Core Entity Relationships
The system implements a comprehensive CRM structure with the following key relationships:

**Primary Entities:**
- `Users` (Platform users/agents)
- `Companies` (Multi-tenant structure)
- `Accounts` (Customer companies)
- `Contacts` (Individual contacts)
- `Leads` (Sales prospects)

**Telephony Integration:**
- `Calls` - Links to Accounts, Contacts, Leads, Campaigns, and Deals
- `CDR` - Asterisk call detail records
- `SMS` - SMS messaging linked to Leads, Contacts, Accounts, Campaigns

**Business Process Entities:**
- `Campaigns` - Many-to-many with Leads, Contacts, Accounts
- `Deals` - Linked to Accounts, Contacts, Leads
- `Invoices/Orders/Quotes` - Financial transactions with product line items
- `Tickets` - Support cases linked to Accounts, Contacts
- `Documents` - File management with many-to-many relationships

**Activity Tracking:**
- `activity_log` - Comprehensive audit trail using Spatie ActivityLog
- `Comments` - Commentable trait for all major entities
- `Calendar/Events` - Scheduling integration

#### Migration Analysis
Based on 150+ migration files, the database has evolved significantly with:
- Multi-tenancy support (`company_id` fields)
- Soft deletes on most entities
- Comprehensive foreign key relationships
- Asterisk-specific tables (`queuelog`, `cdr`, network configurations)
- Advanced features (tags, attachments, currencies, taxes)

### 5. Telephony Features Currently Managed by FreePBX

#### Extension Management
- **SIP/PJSIP Extensions:** FreePBX manages registration, authentication
- **Dialplan Routing:** Auto-generated extension logic
- **Voicemail Integration:** FreePBX voicemail system

#### Call Routing & IVR
- **Inbound Routing:** DID management and call distribution
- **IVR Systems:** Interactive voice response handling
- **Queue Management:** ACD queue configuration and monitoring

#### Trunk Management
- **SIP Trunks:** Provider connectivity and authentication
- **Outbound Routing:** Least cost routing and failover
- **Codec Management:** Audio codec negotiations

#### Reporting & Monitoring
- **Real-time Monitoring:** Extension states and call progress
- **Call Statistics:** Queue statistics and performance metrics
- **System Health:** Asterisk system monitoring

## FreePBX Removal Strategy

### Phase 1: Analysis & Preparation (Weeks 1-2)

#### 1.1 Dependency Mapping
- [ ] Catalog all FreePBX-generated configuration files
- [ ] Identify custom dialplan modifications that depend on FreePBX
- [ ] Map current extension numbering scheme and routing logic
- [ ] Document IVR flows and queue configurations
- [ ] Analyze trunk configurations and provider integrations

#### 1.2 Custom Configuration Preparation
- [ ] Create native Asterisk configuration templates
- [ ] Design new extension management system
- [ ] Plan database schema for Asterisk configuration storage
- [ ] Prepare migration scripts for existing extensions

### Phase 2: Direct Asterisk Configuration Management (Weeks 3-6)

#### 2.1 Configuration Management Module
Create a new Laravel module `Modules/Asterisk/` to handle:

**Entities to Create:**
- `Extension` - SIP/PJSIP extension configuration
- `Trunk` - SIP trunk configurations  
- `DialplanContext` - Custom dialplan management
- `Queue` - ACD queue configuration
- `IvrMenu` - IVR menu definitions
- `DidRoute` - Inbound DID routing rules

**Configuration Templates:**
```php
// Example: Extension configuration management
class Extension extends Model {
    protected $fillable = [
        'extension_number',
        'user_id', 
        'transport', // UDP/TCP/TLS
        'codec_config',
        'nat_settings',
        'context',
        'company_id'
    ];
    
    public function generatePjsipConfig() {
        // Generate PJSIP endpoint configuration
    }
}
```

#### 2.2 Dialplan Management System
- Replace FreePBX dialplan generation with custom logic
- Create web-based dialplan editor
- Implement context-based routing
- Maintain backward compatibility with existing numbers

#### 2.3 Real-time Configuration Updates
- Implement Asterisk AMI configuration reloads
- Create configuration validation system
- Build rollback mechanism for failed changes

### Phase 3: Feature Migration (Weeks 7-12)

#### 3.1 Extension Management
- [ ] Web-based extension creation/modification
- [ ] User self-service portal for basic extension settings
- [ ] Bulk extension provisioning tools
- [ ] Integration with user management system

#### 3.2 Call Routing Enhancement
- [ ] Advanced call routing rules engine
- [ ] Time-based routing
- [ ] Geographic routing
- [ ] Caller ID-based routing
- [ ] Custom routing conditions

#### 3.3 IVR System Rebuild
- [ ] Graphical IVR designer
- [ ] Dynamic IVR menu generation
- [ ] Multi-language support
- [ ] Voice prompt management
- [ ] Statistical tracking

#### 3.4 Queue Management Enhancement
- [ ] Advanced queue configuration
- [ ] Real-time agent management
- [ ] Queue statistics dashboard
- [ ] Skill-based routing
- [ ] Callback queue functionality

### Phase 4: Enhanced Features (Weeks 13-16)

#### 4.1 Advanced Call Features
- [ ] Click-to-dial from CRM
- [ ] Call recording management
- [ ] Call transfer enhancements
- [ ] Conference room management
- [ ] Voicemail-to-email integration

#### 4.2 Integration Enhancements  
- [ ] CRM deep integration (screen pops, auto-logging)
- [ ] SMS integration improvements
- [ ] API for third-party integrations
- [ ] Webhook support for real-time events

#### 4.3 Monitoring & Analytics
- [ ] Advanced call analytics
- [ ] Real-time dashboards
- [ ] Performance monitoring
- [ ] Capacity planning tools
- [ ] Custom reporting engine

## Laravel Framework Upgrade Roadmap

### Current State: Laravel 8/9
### Target State: Laravel 10/11 LTS

#### Phase 1: Pre-Upgrade Preparation (Week 1)

##### 1.1 Dependency Analysis
**Current Key Dependencies to Update:**
```json
{
  "laravel/framework": "8.*|9.*" → "^10.0|^11.0",
  "php": ">=7.3.0" → "^8.1|^8.2",
  "spatie/laravel-permission": "3.*" → "^5.0|^6.0",
  "nwidart/laravel-modules": "5.*" → "^10.0",
  "yajra/laravel-datatables-oracle": "9.*" → "^10.0"
}
```

##### 1.2 PHP Compatibility
- [ ] Update PHP version to 8.1+ (required for Laravel 10)
- [ ] Test all custom code for PHP 8.1+ compatibility  
- [ ] Update deprecated PHP functions and syntax
- [ ] Verify third-party package compatibility

##### 1.3 Code Audit
- [ ] Identify deprecated Laravel features in use
- [ ] Update Eloquent model casting syntax
- [ ] Review custom middleware implementations
- [ ] Check for breaking changes in package APIs

#### Phase 2: Framework Upgrade (Weeks 2-3)

##### 2.1 Laravel 10 Upgrade
- [ ] Update composer.json dependencies
- [ ] Run `php artisan laravel:upgrade` (if available)
- [ ] Update configuration files
- [ ] Migrate deprecated Eloquent features
- [ ] Update validation rules syntax

##### 2.2 Package Updates
- [ ] Update each module dependency individually
- [ ] Test DataTables functionality (major breaking changes expected)
- [ ] Update Spatie packages (ActivityLog, Permissions)
- [ ] Verify multi-tenancy package compatibility

##### 2.3 Breaking Changes Resolution
**Expected Breaking Changes:**
- Route model binding updates
- Eloquent date casting changes  
- Middleware signature changes
- Config file structure updates
- Blade directive changes

#### Phase 3: Feature Enhancement (Week 4)

##### 3.1 Laravel 10/11 New Features Integration
- [ ] Implement new Eloquent features
- [ ] Utilize improved validation
- [ ] Adopt new Blade components
- [ ] Implement process pools for background tasks
- [ ] Use new HTTP client features

##### 3.2 Performance Optimizations
- [ ] Implement Laravel Octane (if applicable)
- [ ] Optimize database queries with new Eloquent features  
- [ ] Implement improved caching strategies
- [ ] Use new queue improvements

## Database Upgrade Strategy

### Current: MariaDB/MySQL 5.7+
### Target: MariaDB 10.6+ / MySQL 8.0+

#### Phase 1: Database Analysis & Preparation
- [ ] Analyze current database performance
- [ ] Identify indexing improvements
- [ ] Review stored procedures (if any)
- [ ] Plan for JSON field optimizations

#### Phase 2: Schema Enhancements
- [ ] Add database-level constraints
- [ ] Implement better indexing strategy
- [ ] Optimize foreign key relationships
- [ ] Add full-text search indexes

## Testing Strategy

### Automated Testing Implementation
```php
// Example: Asterisk Integration Testing
class AsteriskIntegrationTest extends TestCase {
    public function test_ami_connection() {
        // Test AMI connectivity
    }
    
    public function test_extension_creation() {
        // Test extension management
    }
    
    public function test_call_origination() {
        // Test call functionality
    }
}
```

### Testing Phases
1. **Unit Testing:** Core functionality testing
2. **Integration Testing:** Module interaction testing  
3. **Telephony Testing:** Asterisk integration testing
4. **Performance Testing:** Load and stress testing
5. **User Acceptance Testing:** Business workflow validation

## Deployment Strategy

### Environment Preparation
1. **Development Environment:** Complete refactoring and testing
2. **Staging Environment:** Full feature testing and validation
3. **Production Migration:** Phased rollout with rollback plan

### Rollback Strategy
- Complete database backups
- Configuration file backups
- Service-level rollback procedures
- Traffic routing fallback plans

## Risk Mitigation

### High-Risk Areas
1. **Asterisk Configuration:** Risk of service interruption
2. **Database Migration:** Data consistency issues
3. **Third-party Integrations:** API compatibility problems
4. **User Training:** Workflow disruption

### Mitigation Strategies
- Comprehensive testing protocols
- Staged deployment approach
- Real-time monitoring during migration  
- 24/7 support during transition periods
- Complete rollback procedures

## Success Metrics

### Performance Metrics
- System response time improvements
- Database query optimization results
- Memory usage optimization
- Concurrent user capacity

### Business Metrics  
- Feature availability during migration
- User satisfaction scores
- System stability measurements
- Integration success rates

## Timeline Summary

| Phase | Duration | Key Deliverables |
|-------|----------|------------------|
| Analysis & Preparation | Weeks 1-2 | Complete system analysis, migration plan |
| FreePBX Removal | Weeks 3-12 | Direct Asterisk integration, feature migration |
| Laravel Upgrade | Weeks 2-4 | Framework modernization |  
| Testing & Validation | Weeks 13-16 | Comprehensive testing, user validation |
| Production Migration | Weeks 17-18 | Staged deployment, monitoring |

## Conclusion

This refactoring project will modernize the CC System by:
- Removing FreePBX dependencies for better control and customization
- Upgrading to modern Laravel framework for improved performance and security
- Enhancing telephony integration with direct Asterisk management
- Improving system maintainability and extensibility

The phased approach ensures minimal business disruption while achieving comprehensive system modernization.

---

**Document Version:** 1.0  
**Created:** October 2025  
**Last Updated:** [Current Date]  
**Next Review:** [Review Date]