ai-stylegallery/prp/configuration-settings.md

Configuration and Settings Specification

Overview

Comprehensive configuration management system using Laravel's settings with database storage, environment variables, and runtime configuration for flexible application behavior.

Configuration Architecture

Configuration Sources (Priority Order)

1. Runtime Settings (Database) - User-configurable application behavior
2. Environment Variables (.env) - Sensitive and environment-specific settings
3. Configuration Files (config/) - Framework and package defaults
4. Hardcoded Defaults - Fallback values in code

┌─────────────────────────────────────────────────────────┐
│                Runtime Settings (Database)              │
│  • User-configurable behavior                           │
│  • Admin-managed settings                              │
│  • Feature flags and toggles                           │
└─────────────────────┬───────────────────────────────────┘
                      │ Priority 1 (Highest)
                      ▼
┌─────────────────────────────────────────────────────────┐
│            Environment Variables (.env)                │
│  • Sensitive credentials                               │
│  • Environment-specific configuration                  │
│  • Deployment-specific settings                        │
└─────────────────────┬───────────────────────────────────┘
                      │ Priority 2
                      ▼
┌─────────────────────────────────────────────────────────┐
│          Configuration Files (config/)                 │
│  • Laravel framework settings                          │
│  • Package configurations                              │
│  • Default application behavior                        │
└─────────────────────┬───────────────────────────────────┘
                      │ Priority 3
                      ▼
┌─────────────────────────────────────────────────────────┐
│             Hardcoded Defaults                         │
│  • Fallback values in code                             │
│  • Emergency defaults                                   │
└─────────────────────────────────────────────────────────┘

Settings Model

Database Structure

Table: settings

Schema:

CREATE TABLE settings (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  key VARCHAR(255) UNIQUE NOT NULL,
  value LONGTEXT NULL,
  created_at TIMESTAMP NULL,
  updated_at TIMESTAMP NULL
);

Model: app/Models/Setting.php

Key Features:

• Unique constraint on key field
• value stored as LONGTEXT for flexibility (JSON, arrays, large strings)
• Automatic timestamps for audit trail

Setting Access Patterns

Simple Value Retrieval:

$value = Setting::where('key', 'app_name')->first()->value ?? 'Default Name';

Type-Safe Access:

// Boolean setting
$enabled = Setting::getBoolean('feature_enabled', false);

// Integer setting
$maxImages = Setting::getInteger('max_images_per_user', 100);

// JSON setting
$parameters = Setting::getJson('api_parameters', []);

Configuration Categories

1. Application Settings

Core Application Behavior:

// Application Identity
'app_name' => 'AI StyleGallery'
'app_description' => 'Transform images with AI styles'
'app_url' => 'https://your-domain.com'

// Gallery Behavior
'gallery_heading' => 'Meine Bildergalerie'
'default_style_id' => 1
'new_image_timespan_minutes' => 60
'image_refresh_interval' => 5  // seconds

// Upload Configuration
'max_upload_size' => 10  // MB
'allowed_image_types' => 'jpeg,jpg,png,webp'
'auto_process_uploaded_images' => false

// UI Configuration
'show_print_button' => true
'default_theme' => 'light'
'default_locale' => 'de'

2. AI Processing Settings

Processing Behavior:

// Timeout Configuration
'comfyui_timeout' => 180  // seconds
'runwareai_timeout' => 60  // seconds
'max_processing_time' => 300  // seconds

// Retry Configuration
'max_retry_attempts' => 3
'retry_delay' => 1000000  // microseconds

// Queue Management
'max_concurrent_processes' => 3
'process_queue_enabled' => true

// Quality Settings
'default_output_quality' => 95  // JPEG quality
'enable_progressive_jpeg' => true

3. Storage Configuration

File Management:

// Storage Paths
'upload_path' => 'uploads/'
'style_preview_path' => 'style_previews/'
'temp_path' => 'temp/'

// Cleanup Settings
'auto_cleanup_temp_files' => true
'temp_file_retention_hours' => 24
'max_storage_per_user_gb' => 5

// CDN Configuration
'cdn_enabled' => false
'cdn_base_url' => 'https://cdn.your-domain.com'

4. Notification Settings

Communication Preferences:

// Email Settings
'email_notifications_enabled' => true
'admin_notification_email' => 'admin@your-domain.com'
'notification_from_email' => 'noreply@your-domain.com'

// Processing Notifications
'notify_on_processing_start' => false
'notify_on_processing_complete' => true
'notify_on_processing_error' => true

// Admin Alerts
'alert_on_high_error_rate' => true
'error_rate_threshold' => 10  // percentage

5. Security Settings

Security Configuration:

// Session Security
'session_lifetime' => 120  // minutes
'admin_session_lifetime' => 60  // minutes
'enable_session_fixation_protection' => true

// Rate Limiting
'login_attempts_per_minute' => 5
'api_rate_limit_per_hour' => 1000

// Content Security
'enable_csp' => true
'csp_report_only' => false

6. Performance Settings

Performance Optimization:

// Caching
'cache_enabled' => true
'cache_ttl' => 3600  // seconds
'style_cache_ttl' => 7200  // seconds

// Image Optimization
'enable_lazy_loading' => true
'thumbnail_size' => 300  // pixels
'preview_quality' => 80  // JPEG quality

// Database Optimization
'query_cache_enabled' => true
'eager_loading_enabled' => true

Environment Configuration

Sensitive Configuration (.env)

# Application
APP_NAME="AI StyleGallery"
APP_ENV=production
APP_KEY=base64:your-app-key-here
APP_URL=https://your-domain.com

# Database
DB_CONNECTION=sqlite
DB_DATABASE=/path/to/database.sqlite

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls

# Redis (for caching)
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Broadcasting (for real-time features)
BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-pusher-id
PUSHER_APP_KEY=your-pusher-key
PUSHER_APP_SECRET=your-pusher-secret
PUSHER_HOST=your-pusher-host
PUSHER_PORT=443
PUSHER_SCHEME=https

# AI Service Credentials
COMFYUI_API_URL=https://your-comfyui-server.com
COMFYUI_API_KEY=your-comfyui-key

RUNWAREAI_API_URL=https://api.runwareai.com
RUNWAREAI_API_TOKEN=your-runwareai-token

Configuration Files

Laravel Configuration (config/)

config/app.php

'locale' => env('APP_LOCALE', 'de'),
'timezone' => env('APP_TIMEZONE', 'Europe/Berlin'),
'key' => env('APP_KEY'),
'cipher' => 'AES-256-CBC',

config/filesystems.php

'public' => [
    'driver' => 'local',
    'root' => public_path('storage'),
    'url' => env('APP_URL').'/storage',
    'visibility' => 'public',
],

config/filament.php

'brand' => [
    'name' => env('APP_NAME', 'AI StyleGallery'),
    'logo' => '/images/logo.png',
],
'auth' => [
    'guard' => 'web',
    'pages' => [
        'login' => \App\Filament\Pages\Login::route('/login'),
    ],
],

Runtime Configuration Management

Setting Access Helpers

Location: app/Services/SettingsService.php

Core Methods:

get(string $key, $default = null)

• Retrieves setting value with optional default
• Automatic type casting for common types

set(string $key, $value): void

• Stores or updates setting value
• Handles type conversion and validation

getBoolean(string $key, bool $default = false): bool

• Retrieves boolean setting with fallback

getInteger(string $key, int $default = 0): int

• Retrieves integer setting with fallback

getJson(string $key, $default = []): array

• Retrieves JSON setting as associative array

Usage Examples:

// Application settings
$appName = Settings::get('app_name', 'AI StyleGallery');
$maxCopies = Settings::getInteger('max_print_copies', 10);
$features = Settings::getJson('enabled_features', []);

// Feature flags
$printEnabled = Settings::getBoolean('show_print_button', true);
$notificationsEnabled = Settings::getBoolean('email_notifications_enabled', true);

Configuration Caching

Cache Strategy:

• Settings cached in Redis/memory for performance
• Automatic cache invalidation on setting changes
• Separate TTL for different setting categories

Implementation:

// Cache key pattern
'settings:' . $key => $value

// Cache TTL by category
'application_settings' => 3600,    // 1 hour
'ai_settings' => 1800,             // 30 minutes
'security_settings' => 7200,       // 2 hours

Admin Configuration Interface

Filament Settings Management

Settings Resource: app/Filament/Resources/SettingResource.php

Features:

• CRUD Interface: Create, read, update, delete settings
• Type Validation: Ensure setting values match expected types
• Bulk Operations: Mass update related settings
• Import/Export: Backup and restore configuration
• Validation: Prevent invalid configuration values

Setting Types:

• Text: Simple string values
• Number: Integer and float values
• Boolean: True/false toggles
• JSON: Complex configuration objects
• Select: Predefined option lists

Settings Categories

Organization:

• General: Application name, description, URLs
• Gallery: Image handling, display options
• AI Processing: Provider settings, timeouts, quality
• Storage: File paths, cleanup, CDN settings
• Notifications: Email, alerts, communication
• Security: Authentication, rate limiting, privacy
• Performance: Caching, optimization, limits

Dynamic Configuration

Feature Flags

Implementation:

// Feature flag checking
if (Settings::getBoolean('enable_batch_processing', false)) {
    // Enable batch processing features
}

// Environment-specific features
if (app()->environment('production')) {
    $features = Settings::getJson('production_features', []);
} else {
    $features = Settings::getJson('development_features', []);
}

Common Feature Flags:

• enable_printing: Show/hide print functionality
• enable_batch_processing: Allow multiple image processing
• enable_social_features: User sharing capabilities
• enable_advanced_styles: Premium style options

Environment-Based Configuration

Automatic Configuration:

// Different settings per environment
$environment = app()->environment();

switch ($environment) {
    case 'production':
        $settings = Settings::getJson('production_overrides', []);
        break;
    case 'staging':
        $settings = Settings::getJson('staging_overrides', []);
        break;
    default:
        $settings = Settings::getJson('development_overrides', []);
}

Configuration Validation

Setting Validation Rules

Validation Framework:

$rules = [
    'app_name' => 'required|string|max:255',
    'max_upload_size' => 'required|integer|min:1|max:100',
    'allowed_image_types' => 'required|string',
    'comfyui_timeout' => 'required|integer|min:30|max:600',
    'cdn_enabled' => 'boolean',
    'api_parameters' => 'nullable|json',
];

Validation Implementation:

// Validate before saving
$validator = Validator::make($settings, $rules);
if ($validator->fails()) {
    throw new ValidationException($validator->errors());
}

// Type conversion
$sanitizedValue = match($setting->type) {
    'boolean' => (bool) $value,
    'integer' => (int) $value,
    'json' => json_decode($value, true),
    default => (string) $value,
};

Configuration Migration

Version Management

Configuration Versions:

• Track configuration schema versions
• Automatic migration of configuration values
• Backup before major configuration changes

Migration Example:

// Configuration migration for new version
if ($currentVersion < 2.0) {
    // Migrate old 'upload_size' to 'max_upload_size'
    $oldValue = Settings::get('upload_size');
    if ($oldValue) {
        Settings::set('max_upload_size', $oldValue * 1024 * 1024); // Convert MB to bytes
        Settings::forget('upload_size');
    }
}

Backup and Restore

Configuration Backup:

// Export all settings
$allSettings = Settings::all();
$backup = [
    'version' => config('app.version'),
    'timestamp' => now()->toISOString(),
    'settings' => $allSettings->pluck('value', 'key')->toArray(),
];

// Save to file
Storage::put('config-backup-' . date('Y-m-d-H-i-s') . '.json', json_encode($backup));

Monitoring and Analytics

Configuration Monitoring

Change Tracking:

• Log all configuration changes
• Track who made changes and when
• Alert on critical configuration modifications

Performance Impact:

• Monitor configuration load times
• Track cache hit/miss ratios
• Alert on configuration-related errors

Analytics Integration

Usage Analytics:

// Track feature usage
if (Settings::getBoolean('analytics_enabled', false)) {
    Analytics::track('feature_used', [
        'feature' => 'style_application',
        'style_id' => $style->id,
        'user_id' => auth()->id(),
    ]);
}

Security Considerations

Sensitive Configuration

Encryption:

• Encrypt sensitive setting values in database
• Use Laravel's encryption helpers for sensitive data
• Separate encryption keys for different environments

Access Control:

• Restrict sensitive settings to admin users only
• Audit trail for sensitive configuration changes
• Automatic masking in logs and exports

Configuration Injection Prevention

Input Sanitization:

• Validate all configuration inputs
• Prevent code injection through configuration
• Escape special characters in configuration values

Deployment Configuration

Environment-Specific Settings

Deployment Pipeline:

// Production deployment
Settings::set('app_environment', 'production');
Settings::set('cdn_enabled', true);
Settings::set('debug_mode', false);

// Development deployment
Settings::set('app_environment', 'development');
Settings::set('cdn_enabled', false);
Settings::set('debug_mode', true);

Configuration Synchronization

Multi-Server Setup:

• Synchronize configuration across web servers
• Handle configuration updates without downtime
• Validate configuration consistency

Troubleshooting Configuration

Common Issues

Configuration Not Loading:

• Check database connectivity
• Verify settings table exists
• Validate setting key names

Performance Issues:

• Monitor configuration cache hit rates
• Check for configuration-related database queries
• Optimize frequently accessed settings

Type Mismatches:

• Ensure proper type casting in code
• Validate setting types in admin interface
• Handle legacy configuration gracefully

Debug Tools

Configuration Inspector:

// Development-only configuration debugging
if (app()->environment('local')) {
    Route::get('/admin/config-debug', function () {
        return [
            'all_settings' => Settings::all(),
            'environment' => app()->environment(),
            'cached_settings' => Cache::get('settings:*'),
        ];
    });
}

Future Configuration Enhancements

Advanced Features

Configuration Templates:

• Predefined configuration sets for different use cases
• One-click configuration application
• Configuration comparison and diff tools

Dynamic Configuration:

• Real-time configuration updates
• Hot-reloading of configuration changes
• A/B testing for configuration options

External Configuration:

• Integration with external configuration management systems
• Cloud-based configuration storage
• Configuration sharing across projects

Configuration API

RESTful Configuration Management:

• API endpoints for configuration management
• Version control for configuration changes
• Configuration validation via API

Webhook Integration:

• Notify external systems of configuration changes
• Trigger deployments on configuration updates
• Integrate with monitoring and alerting systems