# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Laravel-based softphone application that enables browser-to-phone and browser-to-browser calls using Twilio Client. The application provides a customer support ticketing system with integrated voice calling capabilities.

**Recent Updates**: 
- Successfully upgraded from Laravel 7.x to Laravel 12.x (January 2025) with PHP 8.4.5 support
- Updated all dependencies including Twilio SDK 8.7.0 (latest) and modern Node.js packages

## Key Architecture Components

### Backend Structure
- **Laravel 12.x** framework with PHP 8.2+ (currently running PHP 8.4.5)
- **SQLite** database for local development
- **Twilio SDK 8.7.0** (latest) integration for voice calling functionality
- **Laravel Sanctum 4.x** for API authentication
- **Spatie Laravel Permission 6.x** for role-based access control
- **Laravel Breeze** for authentication scaffolding

### Frontend Components
- **Vite** for modern asset bundling and compilation (replaces Laravel Mix)
- **Bootstrap 5** for UI framework  
- **jQuery 3.7+** for DOM manipulation
- **Twilio Voice SDK 2.x** for browser calling (updated from deprecated twilio-client)
- **Alpine.js** for lightweight JavaScript interactions
- **Tailwind CSS** for utility-first CSS framework
- Custom JavaScript modules: `browser-calls.js`, `dialpad.js`, `voice-call.js`

### Core Functionality
- **Support Ticket System**: Customer support ticket creation and management
- **Voice Calling**: Browser-based calling using Twilio Client
- **Call Logging**: Comprehensive call history and analytics
- **Live Chat**: Real-time customer support chat (with dedicated controllers)
- **User Management**: Multi-tenant company structure with role-based permissions

## Development Commands

### Installation & Setup
```bash
# Install PHP dependencies and setup database
make install

# Install Node.js dependencies
npm install

# Copy environment configuration
cp .env.example .env
```

### Development Server
```bash
# Start Laravel development server (also opens browser)
make serve

# Alternative: Start server without browser
php artisan serve

# Start Vite development server with hot reload
npm run dev

# Build assets for production
npm run build
```

### Testing
```bash
# Run all tests (PHPUnit)
php artisan test

# Alternative PHPUnit command
./vendor/bin/phpunit
```

### Production Build
```bash
# Build optimized assets for production
npm run build
```

## Important Configuration

### Twilio Integration
The application uses both Twilio PHP SDK 8.7.0 and JavaScript Voice SDK 2.x for comprehensive voice functionality:

**PHP Backend Integration:**
- JWT Access Token generation for client authentication
- TwiML response generation for call flow control
- REST API calls for call management and logging

**JavaScript Frontend Integration:**  
- Browser-based calling using `@twilio/voice-sdk` (2.15.0)
- Real-time call status updates and event handling
- Microphone and audio controls

**Required Twilio Configuration (.env):**
- `TWILIO_ACCOUNT_SID` - Your primary Twilio account identifier
- `TWILIO_APPLICATION_SID` - TwiML App SID for voice URL configuration  
- `TWILIO_API_KEY` and `TWILIO_API_SECRET` - API credentials for token generation
- Phone number configuration for inbound/outbound calling

### Database
Uses SQLite for local development (`database/database.sqlite`). Migrations handle:
- User management with company associations
- Call logs and analytics
- Support tickets
- Permission system tables

## Key File Locations

### Controllers
- `app/Http/Controllers/Api/` - API endpoints for Twilio integration
- `app/Http/Controllers/CallController.php` - Main call handling logic
- `app/Http/Controllers/Livechat/` - Live chat functionality

### Models
- `app/User.php` - User model with company relationships
- `app/Company.php` - Multi-tenant company structure
- `app/Models/CallLog.php` - Call history and analytics

### Frontend Assets
- `resources/js/browser-calls.js` - Core Twilio Client integration
- `resources/js/dialpad.js` - Dialpad UI functionality
- `resources/views/` - Blade templates for UI

### Routes
- `routes/web.php` - Web routes for UI
- `routes/api.php` - API endpoints for AJAX and Twilio webhooks

## Testing Structure
- **Feature Tests**: `tests/Feature/` - Integration tests for controllers
- **Unit Tests**: `tests/Unit/` - Unit tests for individual components
- Uses in-memory SQLite for test database