tigerstyle-heat/docs/BACKUP_MODULE_DOCUMENTATION.md

# TigerStyle Heat - Enterprise Backup & Restore Module

## Overview

The TigerStyle Heat Backup & Restore module is an enterprise-grade backup and restore system for WordPress that provides comprehensive site protection with advanced features including chunked processing, multiple compression formats, S3 storage integration, and sophisticated validation systems.

## Features

### Core Backup Features
- **Complete WordPress Backup**: Files + Database with selective inclusion options
- **Chunked Processing**: Handles large sites without memory/timeout issues
- **Multiple Compression**: ZIP, TAR.GZ, TAR.BZ2 with graceful fallback
- **Progress Tracking**: Real-time AJAX progress updates
- **Backup Validation**: Comprehensive integrity checking with checksums
- **Backup Manifest**: Detailed metadata for each backup

### Storage Options
- **Local Storage**: WordPress uploads directory with organized structure
- **S3 Compatible Storage**: Full S3 integration with metadata and encryption
- **S3-Compatible**: Support for MinIO, DigitalOcean Spaces, etc.
- **Storage Stats**: Usage tracking and space monitoring

### Restore Features
- **Safe Restoration**: Validation before restore with rollback backup creation
- **Selective Restore**: Choose files, database, or both
- **Progress Tracking**: Real-time restore progress monitoring
- **URL Management**: Automatic site URL handling during restore

### Advanced Features
- **WordPress Reset**: Remove default content to prepare for restore
- **Database Reset**: Complete database wipe with multi-level confirmation
- **Scheduled Backups**: Automated backups with retention policies
- **Email Notifications**: Success/failure notifications
- **Comprehensive Logging**: Multi-level logging with export capabilities

## Architecture

### Core Classes

#### TigerStyleSEO_Backup_Restore
Main module coordinator that orchestrates all backup operations.

```php
$backup_module = tigerstyle_heat()->get_module('backup_restore');
```

#### TigerStyleSEO_Backup_Engine
Core backup processing engine with chunked file handling.

**Key Methods:**
- `create_backup($options)` - Create new backup
- `backup_database()` - MySQL dump with table-level processing
- `backup_files()` - Recursive file backup with exclusions
- `create_backup_manifest()` - Generate backup metadata

#### TigerStyleSEO_Restore_Engine
Restoration engine with safety checks and validation.

**Key Methods:**
- `restore_backup($options)` - Restore from backup
- `validate_backup_integrity()` - Pre-restore validation
- `create_rollback_backup()` - Safety backup before restore

#### TigerStyleSEO_Storage_Manager
Multi-backend storage management.

**Storage Backends:**
- Local filesystem storage
- S3 Compatible Storage with encryption
- S3-compatible services

#### TigerStyleSEO_Compression_Manager
Multi-format compression with fallback.

**Supported Formats:**
- ZIP (preferred)
- TAR.GZ
- TAR.BZ2
- TAR (uncompressed fallback)

#### TigerStyleSEO_Backup_Logger
Enterprise logging system with multiple outputs.

**Log Levels:**
- Debug, Info, Warning, Error, Critical
- File-based logging with rotation
- Database storage for recent logs
- Email notifications for critical errors

#### TigerStyleSEO_Backup_Validator
Comprehensive backup validation system.

**Validation Checks:**
- File integrity and checksums
- Database structure validation
- Manifest verification
- Cross-platform compatibility

#### TigerStyleSEO_Backup_Scheduler
Automated backup scheduling with retention policies.

**Features:**
- Hourly, daily, weekly, monthly schedules
- System load checking
- Retention policies
- Failure tracking

## Database Schema

### Backup Metadata Table
```sql
CREATE TABLE wp_tigerstyle_backup_metadata (
    id int(11) NOT NULL AUTO_INCREMENT,
    backup_id varchar(255) NOT NULL,
    storage_type varchar(50) NOT NULL,
    file_path text,
    s3_bucket varchar(255),
    s3_key varchar(500),
    s3_url text,
    file_size bigint(20) NOT NULL DEFAULT 0,
    created_at datetime NOT NULL,
    metadata_json text,
    PRIMARY KEY (id),
    UNIQUE KEY backup_id (backup_id)
);
```

### Backup Logs Table
```sql
CREATE TABLE wp_tigerstyle_backup_logs (
    id int(11) NOT NULL AUTO_INCREMENT,
    level varchar(20) NOT NULL,
    message text NOT NULL,
    context longtext,
    user_id int(11) DEFAULT 0,
    ip_address varchar(45),
    created_at datetime NOT NULL,
    PRIMARY KEY (id),
    KEY level (level),
    KEY created_at (created_at)
);
```

## Configuration

### Default Settings
```php
$default_settings = array(
    'compression' => 'zip',
    'storage_location' => 'local',
    'schedule_enabled' => false,
    'schedule_frequency' => 'daily',
    'retention_days' => 30,
    'include_files' => true,
    'include_database' => true,
    'chunk_size' => 5, // MB
    's3_bucket' => '',
    's3_access_key' => '',
    's3_secret_key' => '',
    's3_region' => 'us-east-1',
    's3_endpoint' => '',
    'email_notifications' => false,
    'notification_email' => get_option('admin_email')
);
```

### S3 Configuration
For AWS S3 or S3-compatible services:

```php
$s3_settings = array(
    's3_bucket' => 'your-backup-bucket',
    's3_access_key' => 'AKIA...',
    's3_secret_key' => 'your-secret-key',
    's3_region' => 'us-east-1',
    's3_endpoint' => 'https://s3.amazonaws.com' // Optional for S3-compatible
);
```

## API Usage

### Creating a Backup
```php
$backup_engine = new TigerStyleSEO_Backup_Engine();
$backup_id = $backup_engine->create_backup(array(
    'type' => 'full',
    'compression' => 'zip',
    'storage_location' => 'local',
    'include_files' => true,
    'include_database' => true,
    'description' => 'Manual backup before update'
));
```

### Restoring from Backup
```php
$restore_engine = new TigerStyleSEO_Restore_Engine();
$restore_id = $restore_engine->restore_backup(array(
    'backup_id' => $backup_id,
    'restore_files' => true,
    'restore_database' => true,
    'create_rollback' => true,
    'validate_before_restore' => true
));
```

### Validating a Backup
```php
$validator = new TigerStyleSEO_Backup_Validator();
$result = $validator->validate_backup($backup_id);

if ($result['valid']) {
    echo "Backup is valid";
} else {
    foreach ($result['errors'] as $error) {
        echo "Error: " . $error;
    }
}
```

## AJAX Endpoints

### Backup Operations
- `tigerstyle_create_backup` - Create new backup
- `tigerstyle_restore_backup` - Restore from backup
- `tigerstyle_backup_progress` - Get operation progress
- `tigerstyle_validate_backup` - Validate backup integrity

### Management Operations
- `tigerstyle_delete_backup` - Delete backup
- `tigerstyle_download_backup` - Download backup file
- `tigerstyle_upload_backup` - Upload backup file

### Advanced Operations
- `tigerstyle_reset_wordpress` - Reset WordPress content
- `tigerstyle_reset_database` - Complete database reset
- `tigerstyle_test_s3_connection` - Test S3 connectivity

### Logging & Stats
- `tigerstyle_get_backup_logs` - Retrieve backup logs
- `tigerstyle_backup_stats` - Get backup statistics

## Security Features

### Access Control
- WordPress capability checks (`manage_options`)
- Nonce verification for all operations
- User ID tracking in logs

### Confirmation Systems
- Text confirmation for destructive operations
- Random code generation for database reset
- Multi-level confirmations for critical actions

### Data Protection
- Backup file encryption in S3
- Protected log directory with .htaccess
- Temporary file cleanup
- Secure file handling

## Performance Optimizations

### Memory Management
- Chunked file processing (configurable chunk size)
- Streaming operations for large files
- Memory limit increases where possible
- Garbage collection optimization

### Timeout Handling
- Set unlimited execution time for operations
- Progress tracking for long operations
- Resumable operations where possible

### System Resource Monitoring
- Load average checking before scheduled backups
- Disk space validation
- Concurrent operation prevention

## Error Handling & Recovery

### Backup Failures
- Automatic cleanup of partial backups
- Failure logging with context
- Graceful degradation (compression fallback)
- Retry mechanisms for network operations

### Restore Failures
- Automatic rollback on restore failure
- Progress state preservation
- Detailed error reporting
- Recovery recommendations

### Validation Failures
- Comprehensive integrity checking
- Detailed validation reports
- Granular error categorization
- Recovery suggestions

## Monitoring & Logging

### Log Levels
- **Debug**: Detailed operation information
- **Info**: General operation status
- **Warning**: Non-critical issues
- **Error**: Operation failures
- **Critical**: System-threatening issues

### Log Storage
- File-based logs with rotation (10MB limit)
- Database storage for recent logs (1000 entries)
- WordPress debug.log integration
- Log export functionality

### Notifications
- Email notifications for failures
- Configurable notification levels
- Rate limiting to prevent spam
- Template-based email formatting

## Integration Points

### WordPress Hooks
- `tigerstyle_backup_restore_completed` - After successful restore
- `tigerstyle_backup_created` - After backup creation
- `tigerstyle_backup_scheduled` - Scheduled backup trigger
- `tigerstyle_backup_cleanup` - Cleanup trigger

### Filter Hooks
- `tigerstyle_backup_paths` - Modify backup file paths
- `tigerstyle_backup_logging_enabled` - Control logging
- `tigerstyle_backup_exclude_patterns` - File exclusion patterns

### Admin Integration
- Tab in main TigerStyle Heat admin interface
- Progress indicators and real-time updates
- Comprehensive settings management
- Backup list and management interface

## File Structure

```
includes/
├── modules/
│   └── class-backup-restore.php          # Main module class
└── backup/
    ├── class-backup-engine.php           # Core backup processing
    ├── class-restore-engine.php          # Restoration engine
    ├── class-storage-manager.php         # Multi-backend storage
    ├── class-backup-logger.php           # Comprehensive logging
    ├── class-backup-validator.php        # Integrity validation
    ├── class-backup-scheduler.php        # Automated scheduling
    ├── class-compression-manager.php     # Multi-format compression
    └── ajax-handlers.php                 # AJAX endpoints

admin/
└── pages/
    └── backup-restore.php                # Admin interface
```

## Requirements

### PHP Requirements
- PHP 7.4 or higher
- Memory: 256MB+ recommended
- Execution time: Unlimited for large backups

### WordPress Requirements
- WordPress 5.0 or higher
- `manage_options` capability for users

### System Requirements
- Available disk space (2x backup size recommended)
- ZIP extension (preferred) or TAR support
- cURL for S3 operations
- MySQL/MariaDB access for database operations

### Optional Requirements
- AWS SDK for advanced S3 features
- ionCube for PHP acceleration
- WP-CLI for command-line operations

## Best Practices

### Backup Strategy
1. **Regular Schedules**: Set up automated daily/weekly backups
2. **Before Updates**: Always backup before major updates
3. **Multiple Locations**: Use both local and S3 storage
4. **Retention Policies**: Keep 30 days of backups minimum
5. **Test Restores**: Regularly test backup restoration

### Security Practices
1. **S3 Permissions**: Use dedicated IAM user with minimal permissions
2. **Backup Encryption**: Enable S3 server-side encryption
3. **Access Control**: Limit backup access to administrators
4. **Log Monitoring**: Monitor backup logs for suspicious activity

### Performance Optimization
1. **Chunk Size**: Adjust based on server resources (5MB default)
2. **Exclusion Patterns**: Exclude unnecessary files (cache, logs)
3. **Compression**: Use ZIP for best compatibility and speed
4. **Scheduling**: Run backups during low-traffic hours

## Troubleshooting

### Common Issues

#### Memory Exhaustion
- Reduce chunk size in settings
- Exclude large directories (uploads/cache)
- Increase PHP memory limit
- Use streaming operations

#### Timeout Issues
- Set unlimited execution time
- Use chunked processing
- Check server timeout settings
- Monitor progress tracking

#### S3 Connection Issues
- Verify credentials and permissions
- Check bucket region settings
- Test with S3 endpoint override
- Monitor network connectivity

#### Validation Failures
- Check file permissions
- Verify backup integrity
- Review compression settings
- Check available disk space

### Debug Mode
Enable WordPress debug mode for detailed logging:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

## Changelog

### Version 1.0.0
- Initial release with core backup/restore functionality
- S3 storage integration
- Comprehensive logging system
- Advanced validation and safety features
- Enterprise-grade admin interface
- Automated scheduling and retention policies

---

## Support

For technical support, please review the logs first:
1. Check backup logs in the admin interface
2. Review WordPress debug logs
3. Verify system requirements
4. Test with minimal configuration

This module represents enterprise-grade backup functionality that can compete with premium backup plugins while being deeply integrated with the TigerStyle Heat ecosystem.