Skip to content

CLAUDE.md

Latest commit

 

History

History
244 lines (176 loc) · 7.1 KB

CLAUDE.md

File metadata and controls

244 lines (176 loc) · 7.1 KB

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:

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

# 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

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' => 'old@example.com',
    'new_email' => 'new@example.com'
]);

Cleanup & Maintenance

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

# 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)

ACTIVITY_LOG_QUEUE=true
ACTIVITY_LOG_QUEUE_CONNECTION=redis

Disabling

To completely disable activity logging:

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:

# 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):

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