# User Creation Mechanism Analysis

## Overview
This document provides a detailed analysis of the user creation process in the Call Center System, which involves creating users in the Laravel application database and automatically provisioning corresponding extensions in the FreePBX/Asterisk PBX system.

## Process Flow

### 1. GUI User Creation Form
**Location**: `Modules/Platform/User/Http/Forms/UserForm.php`
**Route**: `settings.users.create` (GET) → `settings.users.store` (POST)

**Form Fields**:
- **Required Fields**:
  - `first_name` (text) - User's first name
  - `last_name` (text) - User's last name
  - `email` (email) - Unique email address
  - `language_id` (select) - User interface language
  - `date_format_id` (select) - Date display format
  - `time_format_id` (select) - Time display format
  - `time_zone` (select) - User's timezone
  - `theme` (select) - UI theme selection

- **Optional Fields**:
  - `id` (text) - Extension number (3-8 digits, must be unique)
  - `password` (password) - If not provided, auto-generated
  - `company_id` (select) - Company association (admin only)
  - `roles` (multiselect) - User roles/permissions
  - Various profile fields (title, department, phones, address, etc.)

**Validation Rules** (`UserCreateRequest.php`):
- `first_name`: required, max 255 chars
- `id`: nullable, integer, 3-8 digits, unique in users table
- `email`: required, valid email, unique (excluding soft-deleted)
- Language, date/time format, timezone, theme: required

### 2. Controller Processing
**Location**: `Modules/Platform/User/Http/Controllers/User/UserController.php`
**Method**: `store()`

**Steps**:
1. **Request Validation**: Validates input using `UserCreateRequest`
2. **Name Construction**: Combines `first_name + ' ' + last_name` into `name` field
3. **Password Handling**:
   - If password provided: hash with `bcrypt()`
   - If no password: generate random 6-character password, hash it
4. **Company Limits Check** (non-admin users):
   - Count existing users for company
   - Check against `company.user_limit`
   - Block creation if limit exceeded
5. **User Creation**: `$entity = $this->repository->create($input)`
6. **Role Assignment**:
   - Sync roles using `syncRoles()`
   - Admin users can assign any role
   - Non-admin users cannot assign 'admin' role
7. **Asterisk Extension Creation**: `$this->userService->addAsteriskUser($entity, $passwordTemp)`
8. **FreePBX Reload**: Execute `fwconsole reload` to apply changes
9. **Success Response**: Redirect to user index with success message

### 3. Asterisk Extension Creation
**Location**: `Modules/Platform/User/Service/UserService.php`
**Method**: `addAsteriskUser()`

**Steps**:
1. **Name Parsing**: Split full name into first/last name components
2. **Data Preparation**:
   - `extension`: User ID (same as user.id)
   - `sipname`: User ID
   - `firstname`, `lastname`: Parsed from user name
   - `secret`: Plain text password (before hashing)
3. **FreePBX API Call**: `curlCore()` POST to `http://127.0.0.1/pbxCore.php`
4. **FindMeFollow Setup**: Insert into `asterisk.findmefollow` table
5. **Cleanup**: Remove conflicting voicemail/extension entries

### 4. FreePBX Extension Provisioning
**Location**: `public/pbxCore.php`
**Security**: Restricted to localhost (127.0.0.1) requests only

**FreePBX Operations**:
1. **Database Configuration**: Load FreePBX config (`/etc/freepbx.conf`)
2. **Extension Array Construction**: Build comprehensive extension config array
3. **Bulk Import**: `FreePBX::Core()->bulkhandlerImport('extensions', $exts, 1)`
4. **User Management**: `FreePBX::Userman()->bulkhandlerImport('usermanusers', $users, 1)`
5. **WebRTC Enable**: `FreePBX::Webrtc()->ucpUpdateUser($usermanID, 'userman', 'enabled', array())`
6. **Core Update**: `core_users_edit()` to finalize user setup
7. **Reload Trigger**: `needreload()` to apply Asterisk configuration

### 5. Database Schema

#### Laravel Users Table
```sql
CREATE TABLE users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255),           -- first_name + ' ' + last_name
    email VARCHAR(255) UNIQUE,
    password VARCHAR(255),       -- bcrypt hashed
    first_name VARCHAR(255),
    last_name VARCHAR(255),
    -- ... other profile fields
    company_id INT,
    is_active BOOLEAN DEFAULT 1,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP NULL   -- soft deletes
);
```

#### FreePBX Tables Affected
- `asterisk.users` - Extension user records
- `asterisk.devices` - Device configurations
- `asterisk.sip` - SIP peer settings
- `asterisk.userman_users` - User manager accounts
- `asterisk.cxpanel_users` - Call center panel users
- `asterisk.findmefollow` - Follow-me/call forwarding
- `asterisk.webrtc_clients` - WebRTC client configurations

## Extension Configuration Details

### PJSIP Extension Settings
- **Extension**: User ID (same as Laravel user.id)
- **Technology**: PJSIP
- **Dial String**: `PJSIP/{extension}`
- **Context**: `from-internal`
- **CallerID**: `{firstname} {lastname} <{extension}>`
- **Mailbox**: `{extension}@device`
- **DTMF Mode**: RFC4733
- **Codecs**: All enabled (ULAW, ALAW, GSM, etc.)
- **NAT**: Yes, RTP symmetric, force_rport
- **Security**: MD5 secret authentication

### WebRTC Configuration
- **Enabled**: Yes for UCP (User Control Panel)
- **ICE Support**: Yes
- **Bundle**: No
- **RTCP Mux**: Yes
- **DTLS**: No
- **SRTP**: No

### FindMeFollow Settings
- **Group Number**: Extension number
- **Strategy**: `ringallv2-prim`
- **Ring Time**: 20 seconds
- **Ring Group**: Extension number
- **Post Destination**: `ext-local,{extension},dest`

## Security Considerations

### Access Control
- **IP Restriction**: pbxCore.php only accepts 127.0.0.1 requests
- **Authentication**: No additional auth (relies on localhost restriction)
- **Permission Checks**: Controller validates user permissions for role assignment

### Password Handling
- **Storage**: Laravel uses bcrypt hashing
- **Transmission**: Plain text to FreePBX (localhost only)
- **FreePBX Storage**: Base64 encoded in userman_users.encrypted_password

## Error Handling & Troubleshooting

### Common Issues
1. **Extension Already Exists**: Check for duplicate user IDs
2. **FreePBX Connection Failed**: Verify FreePBX service status
3. **Database Lock**: Ensure no concurrent user creation
4. **Permission Denied**: Check file permissions on pbxCore.php

### Recovery Procedures
1. **Failed Extension Creation**: Manual cleanup required
2. **Partial Creation**: Delete user and retry, or manual FreePBX cleanup
3. **Reload Failure**: Manual `fwconsole reload` execution

### Monitoring Points
- **Laravel Logs**: User creation attempts and failures
- **FreePBX Logs**: Extension provisioning results
- **Asterisk CLI**: `sip show peers` to verify extension registration

## Integration Points

### External Systems
- **FreePBX Core**: Extension and device management
- **Asterisk Manager**: Real-time call processing
- **User Control Panel**: WebRTC and user settings
- **Call Center Panel**: Agent status and queue management

### API Dependencies
- **FreePBX API**: Bulk import operations
- **User Manager API**: User account creation
- **WebRTC API**: Client configuration
- **Core API**: Extension finalization

## Maintenance Notes

### Configuration Files
- `/etc/freepbx.conf` - FreePBX database credentials
- `.env` - Laravel environment settings
- `config/database.php` - Database connections

### Backup Considerations
- **Laravel Database**: Standard mysqldump
- **FreePBX Database**: `asterisk` database backup
- **Configuration Files**: FreePBX config backup

### Upgrade Path
- Test user creation after FreePBX upgrades
- Verify API compatibility
- Update extension templates as needed

## Process Dependencies

### Required Services
1. **MySQL/MariaDB**: Both Laravel and FreePBX databases
2. **FreePBX**: PBX management interface
3. **Asterisk**: Telephony engine
4. **HTTP Server**: For pbxCore.php access

### File Permissions
- `public/pbxCore.php`: Executable by web server
- FreePBX config files: Readable by web server user
- Asterisk directories: Writable for configuration updates

This completes the comprehensive analysis of the user creation mechanism, covering the complete flow from GUI form submission through database operations to FreePBX/Asterisk integration.