wave Agent Skills & AI Rules

# CLAUDE.md

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

## Overview

Wave is a Laravel-based SaaS framework that provides essential features for building subscription-based applications. The application uses a modular architecture with themes, plugins, and a custom admin panel built with Filament.

## Development Commands

### Frontend Development
- `npm run dev` - Start Vite development server
- `npm run build` - Build assets for production

### Backend Development
- `php artisan serve` - Start Laravel development server
- `composer run dev` - Start full development environment (server, queue, logs, and Vite)

### Database & Migrations
- `php artisan migrate` - Run database migrations
- `php artisan db:seed` - Seed the database
- `php artisan migrate:fresh --seed` - Fresh migration with seeding

### Testing
- `php artisan test` - Run PHPUnit tests
- `vendor/bin/pest` - Run Pest tests

### Queue Management
- `php artisan queue:work` - Process queued jobs
- `php artisan queue:listen --tries=1` - Listen for jobs with retry limit

### Wave-Specific Commands
- `php artisan wave:cancel-expired-subscriptions` - Cancel expired subscriptions
- `php artisan wave:create-plugin` - Create a new plugin

## Architecture Overview

### Core Structure
- `app/` - Standard Laravel application files
- `wave/` - Wave framework core files and components
- `resources/themes/` - Theme files (Blade templates, assets)
- `resources/plugins/` - Plugin system files
- `config/wave.php` - Main Wave configuration

### Key Components

#### Wave Service Provider (`wave/src/WaveServiceProvider.php`)
- Registers middleware, Livewire components, and Blade directives
- Handles plugin registration and theme management
- Configures Filament colors and authentication

#### Models & Database
- User model extends Wave User with subscription capabilities
- Subscription management with Stripe/Paddle integration
- Role-based permissions using Spatie Laravel Permission

#### Theme System
- Multiple themes available in `resources/themes/`
- Theme switching in demo mode via cookies
- Folio integration for page routing

#### Admin Panel
- Filament-based admin interface
- Resource management for users, posts, plans, etc.
- Located in `app/Filament/`

### Billing Integration
- Supports both Stripe and Paddle
- Configured via `config/wave.php` and environment variables
- Webhook handling for subscription events

### Plugin System
- Plugins located in `resources/plugins/`
- Auto-loading via `PluginServiceProvider`
- Plugin creation command available

## Configuration

### Environment Variables
- `WAVE_DOCS` - Show/hide documentation
- `WAVE_DEMO` - Enable demo mode
- `WAVE_BAR` - Show development bar
- `BILLING_PROVIDER` - Set to 'stripe' or 'paddle'

### Important Config Files
- `config/wave.php` - Main Wave configuration
- `config/themes.php` - Theme configuration
- `config/settings.php` - Application settings

## Testing

The application uses Pest for testing with PHPUnit as the underlying framework. Test files are located in `tests/` with separate directories for Feature and Unit tests.

## Development Notes

- The application uses Laravel Folio for page routing
- Livewire components handle dynamic UI interactions
- Filament provides the admin interface
- Theme development follows Blade templating conventions
- Plugin development follows Laravel package conventions

## Performance Optimizations

### Caching Strategy
- User subscription/admin status cached for 5-10 minutes
- Active plans cached for 30 minutes
- Categories cached for 1 hour
- Helper files cached permanently until cleared
- Theme colors cached for 1 hour
- Plugin lists cached for 1 hour

### Cache Clearing
- User caches cleared via `$user->clearUserCache()` method
- Plan caches cleared via `Plan::clearCache()` method
- Category caches cleared via `Category::clearCache()` method

### Database Optimizations
- Eager loading relationships to prevent N+1 queries
- Cached query results for frequently accessed data
- Optimized middleware to use cached user roles

### Usage Tips
- Use `Plan::getActivePlans()` instead of `Plan::where('active', 1)->get()`
- Use `Plan::getByName($name)` instead of `Plan::where('name', $name)->first()`
- Use `Category::getAllCached()` instead of `Category::all()`
- Always clear relevant caches when updating user roles, plans, or categories

### Installation & CI Compatibility
- All caching methods include fallbacks for when cache service is unavailable
- Service provider guards against cache binding issues during package discovery
- Compatible with automated testing environments and CI/CD pipelines

## Activity Log Feature

A simple, performant activity logging system for tracking user actions.

### Configuration

Edit `config/activity.php`:

```php
return [
    // Enable/disable activity logging
    'enabled' => env('ACTIVITY_LOG_ENABLED', true),

    // Queue logs for better performance (recommended for busy apps)
    'queue' => env('ACTIVITY_LOG_QUEUE', false),

    // Queue connection to use
    'queue_connection' => env('ACTIVITY_LOG_QUEUE_CONNECTION', 'database'),

    // How many days to keep logs before auto-deletion
    'retention_days' => env('ACTIVITY_LOG_RETENTION_DAYS', 90),
];
```

### Environment Variables

```env
# Disable activity logging
ACTIVITY_LOG_ENABLED=false

# Enable queued logging (recommended for production)
ACTIVITY_LOG_QUEUE=true
ACTIVITY_LOG_QUEUE_CONNECTION=redis

# Keep logs for 30 days instead of default 90
ACTIVITY_LOG_RETENTION_DAYS=30
```

### Usage

#### Basic Logging

```php
use Wave\ActivityLog;

// Simple log
ActivityLog::log('action_name', 'Description of what happened');

// With metadata
ActivityLog::log('profile_updated', 'User updated their email', [
    'old_email' => '[email protected]',
    'new_email' => '[email protected]'
]);
```

### Cleanup & Maintenance

Activity logs are automatically cleaned up daily to prevent database bloat:

```bash
# Manually clean logs older than configured retention period
php artisan activity:clean

# Clean logs older than specific number of days
php artisan activity:clean --days=30

# Force cleanup without confirmation
php artisan activity:clean --no-interaction
```

The cleanup command runs automatically every day via Laravel's scheduler.

#### Queued (Recommended for Production)
```env
ACTIVITY_LOG_QUEUE=true
ACTIVITY_LOG_QUEUE_CONNECTION=redis
```

### Disabling

To completely disable activity logging:

```env
ACTIVITY_LOG_ENABLED=false
```

## Account Deletion Feature

A scheduled account deletion system that gives users a grace period before permanent deletion.

### Scheduled Command

The system automatically processes scheduled deletions daily:

```bash
# Manually process scheduled deletions
php artisan accounts:process-deletions
```

This command:
1. Finds all users with `deletion_scheduled_at` <= current time
2. Permanently deletes those accounts (force delete)
3. Logs results (success/failure for each account)
4. Returns count of deleted accounts

### Automatic Scheduling

The deletion processor runs automatically every day via Laravel's scheduler (configured in `routes/console.php`):

```php
Schedule::command('accounts:process-deletions')->daily();
```