# Aicoso Wishlist for WooCommerce - Technical Architecture

## Table of Contents
1. [Overview](#overview)
2. [System Architecture](#system-architecture)
3. [Database Design](#database-design)
4. [Core Components](#core-components)
5. [Security Architecture](#security-architecture)
6. [Performance Optimization](#performance-optimization)
7. [Integration Points](#integration-points)
8. [API Design](#api-design)
9. [Frontend Architecture](#frontend-architecture)
10. [Testing Strategy](#testing-strategy)

## Overview

Aicoso Wishlist for WooCommerce is built as a modular WordPress plugin following MVC architecture patterns and WordPress coding standards. The plugin leverages WooCommerce hooks and filters for seamless integration while maintaining independence through its own database tables and session management.

### Key Design Principles
- **Modularity**: Separated concerns with distinct classes for different functionalities
- **Scalability**: Designed to handle thousands of wishlists and millions of items
- **Performance**: Optimized database queries and caching strategies
- **Security**: Input sanitization, nonce verification, and capability checks
- **Extensibility**: Action hooks and filters for third-party customization

## System Architecture

### Layer Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Presentation Layer                       │
│  (Frontend Views, Admin UI, AJAX Handlers, REST API)        │
├─────────────────────────────────────────────────────────────┤
│                     Business Logic Layer                     │
│  (Core Classes, Session Management, Wishlist Operations)    │
├─────────────────────────────────────────────────────────────┤
│                      Data Access Layer                       │
│  (Database Abstraction, Cache Management, Query Builder)    │
├─────────────────────────────────────────────────────────────┤
│                      Infrastructure Layer                    │
│  (WordPress Core, WooCommerce, Database, File System)       │
└─────────────────────────────────────────────────────────────┘
```

### Component Architecture

```
aicoso-wishlist/
├── includes/                 # Core plugin functionality
│   ├── class-aicoso-wishlist.php           # Main plugin class (Singleton)
│   ├── class-aicoso-wishlist-install.php   # Installation/activation logic
│   ├── class-aicoso-wishlist-db.php        # Database operations
│   ├── class-aicoso-wishlist-session.php   # Session management
│   ├── class-aicoso-wishlist-ajax.php      # AJAX request handlers
│   ├── class-aicoso-wishlist-shortcodes.php # Shortcode definitions
│   ├── class-aicoso-wishlist-frontend.php  # Frontend display logic
│   ├── class-aicoso-wishlist-email.php     # Email functionality
│   ├── class-aicoso-wishlist-privacy.php   # Privacy/GDPR compliance
│   └── class-aicoso-wishlist-api.php       # REST API endpoints
├── admin/                    # Admin functionality
│   ├── class-aicoso-wishlist-admin.php     # Admin interface
│   ├── class-aicoso-wishlist-settings.php  # Settings management
│   └── class-aicoso-wishlist-analytics.php # Analytics dashboard
├── public/                   # Public-facing functionality
│   ├── class-aicoso-wishlist-public.php    # Public controller
│   └── class-aicoso-wishlist-social.php    # Social sharing
├── templates/                # Template files
│   ├── wishlist-view.php
│   ├── wishlist-manage.php
│   ├── wishlist-button.php
│   └── email/
├── assets/                   # Static resources
│   ├── css/
│   ├── js/
│   └── images/
└── languages/               # Translation files
```

## Database Design

### Tables Structure

#### Table: `wp_aicoso_wishlists`
```sql
CREATE TABLE wp_aicoso_wishlists (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    user_id BIGINT(20) UNSIGNED DEFAULT NULL,
    session_id VARCHAR(255) DEFAULT NULL,
    wishlist_token VARCHAR(64) NOT NULL,
    wishlist_name VARCHAR(255) NOT NULL DEFAULT 'My Wishlist',
    wishlist_slug VARCHAR(255) NOT NULL,
    privacy ENUM('public', 'shared', 'private') DEFAULT 'public',
    is_default TINYINT(1) DEFAULT 0,
    date_created DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    date_modified DATETIME DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
    expiration DATETIME DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY wishlist_token (wishlist_token),
    KEY user_id (user_id),
    KEY session_id (session_id),
    KEY privacy (privacy),
    KEY date_created (date_created)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

#### Table: `wp_aicoso_wishlist_items`
```sql
CREATE TABLE wp_aicoso_wishlist_items (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    wishlist_id BIGINT(20) UNSIGNED NOT NULL,
    product_id BIGINT(20) UNSIGNED NOT NULL,
    variation_id BIGINT(20) UNSIGNED DEFAULT NULL,
    quantity INT(11) DEFAULT 1,
    position INT(11) DEFAULT 0,
    date_added DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    date_modified DATETIME DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
    product_meta LONGTEXT DEFAULT NULL,
    PRIMARY KEY (id),
    UNIQUE KEY wishlist_product (wishlist_id, product_id, variation_id),
    KEY wishlist_id (wishlist_id),
    KEY product_id (product_id),
    KEY date_added (date_added),
    FOREIGN KEY (wishlist_id) REFERENCES wp_aicoso_wishlists(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

#### Table: `wp_aicoso_wishlist_analytics`
```sql
CREATE TABLE wp_aicoso_wishlist_analytics (
    id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
    product_id BIGINT(20) UNSIGNED NOT NULL,
    event_type ENUM('added', 'removed', 'purchased', 'shared') NOT NULL,
    user_id BIGINT(20) UNSIGNED DEFAULT NULL,
    wishlist_id BIGINT(20) UNSIGNED DEFAULT NULL,
    event_date DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY product_id (product_id),
    KEY event_type (event_type),
    KEY event_date (event_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### Database Optimization Strategies
- **Indexing**: Strategic indexes on frequently queried columns
- **Query Caching**: WordPress transient API for expensive queries
- **Batch Operations**: Bulk insert/update for multiple items
- **Lazy Loading**: Load wishlist items only when needed
- **Data Pruning**: Automatic cleanup of expired guest wishlists

## Core Components

### 1. Main Plugin Class (`Aicoso_Wishlist`)
- **Pattern**: Singleton
- **Responsibilities**:
  - Plugin initialization
  - Hook registration
  - Component loading
  - Dependency injection

### 2. Session Management (`Aicoso_Wishlist_Session`)
- **Features**:
  - Guest user session handling via cookies
  - Registered user session via user meta
  - Session migration on user registration
  - Session expiration management

### 3. Database Operations (`Aicoso_Wishlist_DB`)
- **Features**:
  - CRUD operations for wishlists and items
  - Query builder pattern
  - Prepared statements for security
  - Transaction support

### 4. AJAX Handler (`Aicoso_Wishlist_Ajax`)
- **Endpoints**:
  - `add_to_wishlist`
  - `remove_from_wishlist`
  - `create_wishlist`
  - `update_wishlist`
  - `load_wishlist_items`
  - `bulk_add_to_cart`

### 5. Frontend Display (`Aicoso_Wishlist_Frontend`)
- **Responsibilities**:
  - Button rendering
  - Wishlist page display
  - Template loading
  - Asset enqueueing

## Security Architecture

### Input Validation
```php
// Example validation in AJAX handler
public function add_to_wishlist() {
    // Nonce verification
    if (!wp_verify_nonce($_POST['nonce'], 'aicoso_wishlist_nonce')) {
        wp_die('Security check failed');
    }
    
    // Capability check
    if (!current_user_can('read')) {
        wp_die('Insufficient permissions');
    }
    
    // Input sanitization
    $product_id = absint($_POST['product_id']);
    $wishlist_id = sanitize_text_field($_POST['wishlist_id']);
    
    // Validation
    if (!wc_get_product($product_id)) {
        wp_send_json_error('Invalid product');
    }
}
```

### SQL Injection Prevention
- Use of WordPress `$wpdb->prepare()` for all queries
- Parameterized queries
- Input type casting

### XSS Prevention
- Output escaping with `esc_html()`, `esc_attr()`, `esc_url()`
- Sanitization of user inputs
- Content Security Policy headers

### CSRF Protection
- WordPress nonce system for all forms and AJAX requests
- Token validation for public wishlist access

## Performance Optimization

### Caching Strategy
```php
class Aicoso_Wishlist_Cache {
    // Cache keys
    const CACHE_GROUP = 'aicoso_wishlist';
    const CACHE_VERSION = '1.0.0';
    
    // Cache methods
    public function get_wishlist($wishlist_id) {
        $cache_key = 'wishlist_' . $wishlist_id;
        $cached = wp_cache_get($cache_key, self::CACHE_GROUP);
        
        if (false === $cached) {
            $cached = $this->fetch_from_db($wishlist_id);
            wp_cache_set($cache_key, $cached, self::CACHE_GROUP, HOUR_IN_SECONDS);
        }
        
        return $cached;
    }
    
    public function invalidate_wishlist($wishlist_id) {
        $cache_key = 'wishlist_' . $wishlist_id;
        wp_cache_delete($cache_key, self::CACHE_GROUP);
    }
}
```

### Database Query Optimization
- **Eager Loading**: Load related data in single query
- **Pagination**: Limit results for large datasets
- **Selective Columns**: Only select needed columns
- **Query Monitoring**: Debug mode for query analysis

### Asset Optimization
- **Minification**: CSS and JS minification in production
- **Lazy Loading**: Load assets only on required pages
- **CDN Support**: Compatible with CDN services
- **Image Optimization**: Optimized icons and sprites

## Integration Points

### WooCommerce Hooks
```php
// Product page integration
add_action('woocommerce_after_add_to_cart_button', 'render_wishlist_button');
add_action('woocommerce_after_shop_loop_item', 'render_wishlist_button');

// Cart integration
add_filter('woocommerce_add_to_cart_redirect', 'handle_wishlist_to_cart');

// Order completion
add_action('woocommerce_order_status_completed', 'remove_purchased_items');

// My Account integration
add_filter('woocommerce_account_menu_items', 'add_wishlist_menu');
add_action('woocommerce_account_wishlist_endpoint', 'render_account_wishlist');
```

### WordPress Hooks
```php
// User registration
add_action('user_register', 'migrate_guest_wishlist');

// Admin menu
add_action('admin_menu', 'register_admin_pages');

// Widget registration
add_action('widgets_init', 'register_wishlist_widgets');

// Cron jobs
add_action('aicoso_wishlist_cleanup', 'cleanup_expired_wishlists');
```

## API Design

### REST API Endpoints

#### Endpoint Structure
```
/wp-json/aicoso-wishlist/v1/
├── wishlists/
│   ├── GET    /          # List wishlists
│   ├── POST   /          # Create wishlist
│   ├── GET    /{id}      # Get wishlist
│   ├── PUT    /{id}      # Update wishlist
│   ├── DELETE /{id}      # Delete wishlist
│   └── items/
│       ├── POST   /      # Add item
│       ├── DELETE /{id}  # Remove item
│       └── PUT    /{id}  # Update item
├── public/
│   ├── GET    /search    # Search public wishlists
│   └── GET    /popular   # Popular items
└── analytics/
    └── GET    /stats     # Analytics data
```

#### Authentication
- Cookie authentication for logged-in users
- Token authentication for external applications
- Rate limiting per IP/user

### AJAX API
```javascript
// JavaScript API wrapper
const AicosoWishlist = {
    add: function(productId, wishlistId = null) {
        return jQuery.ajax({
            url: aicoso_wishlist_params.ajax_url,
            type: 'POST',
            data: {
                action: 'aicoso_add_to_wishlist',
                product_id: productId,
                wishlist_id: wishlistId,
                nonce: aicoso_wishlist_params.nonce
            }
        });
    },
    
    remove: function(itemId) {
        // Implementation
    },
    
    create: function(name, privacy) {
        // Implementation
    }
};
```

## Frontend Architecture

### JavaScript Architecture
```javascript
// Module pattern for JavaScript
(function($) {
    'use strict';
    
    window.AicosoWishlistFrontend = {
        init: function() {
            this.bindEvents();
            this.initializeButtons();
        },
        
        bindEvents: function() {
            $(document).on('click', '.aicoso-wishlist-add', this.handleAdd);
            $(document).on('click', '.aicoso-wishlist-remove', this.handleRemove);
        },
        
        handleAdd: function(e) {
            e.preventDefault();
            const $button = $(this);
            const productId = $button.data('product-id');
            
            $button.addClass('loading');
            
            AicosoWishlist.add(productId)
                .done(function(response) {
                    $button.removeClass('loading').addClass('added');
                })
                .fail(function(error) {
                    console.error('Failed to add to wishlist', error);
                });
        }
    };
    
    $(document).ready(function() {
        AicosoWishlistFrontend.init();
    });
})(jQuery);
```

### CSS Architecture
```scss
// BEM methodology for CSS
.aicoso-wishlist {
    &__button {
        &--loading {
            opacity: 0.5;
            cursor: wait;
        }
        
        &--added {
            .aicoso-wishlist__icon {
                fill: red;
            }
        }
    }
    
    &__grid {
        display: grid;
        grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
        gap: 20px;
    }
    
    &__item {
        position: relative;
        
        &-image {
            width: 100%;
            height: auto;
        }
        
        &-actions {
            display: flex;
            justify-content: space-between;
        }
    }
}
```

## Testing Strategy

### Unit Testing
```php
// PHPUnit test example
class Test_Aicoso_Wishlist_DB extends WP_UnitTestCase {
    public function test_create_wishlist() {
        $wishlist_id = Aicoso_Wishlist_DB::create_wishlist([
            'user_id' => 1,
            'wishlist_name' => 'Test Wishlist',
            'privacy' => 'private'
        ]);
        
        $this->assertIsInt($wishlist_id);
        $this->assertGreaterThan(0, $wishlist_id);
    }
    
    public function test_add_item_to_wishlist() {
        // Test implementation
    }
}
```

### Integration Testing
- WooCommerce compatibility testing
- Theme compatibility testing
- Plugin conflict testing
- Performance benchmarking

### Frontend Testing
```javascript
// Jest test example
describe('AicosoWishlist', () => {
    test('should add product to wishlist', async () => {
        const response = await AicosoWishlist.add(123);
        expect(response.success).toBe(true);
        expect(response.data.wishlist_id).toBeDefined();
    });
});
```

### Security Testing
- SQL injection testing
- XSS vulnerability scanning
- CSRF protection validation
- Authentication bypass attempts

## Deployment Architecture

### Environment Configuration
```php
// Environment-specific settings
if (defined('WP_ENV')) {
    switch (WP_ENV) {
        case 'development':
            define('AICOSO_WISHLIST_DEBUG', true);
            define('AICOSO_WISHLIST_CACHE', false);
            break;
        case 'staging':
            define('AICOSO_WISHLIST_DEBUG', false);
            define('AICOSO_WISHLIST_CACHE', true);
            break;
        case 'production':
            define('AICOSO_WISHLIST_DEBUG', false);
            define('AICOSO_WISHLIST_CACHE', true);
            break;
    }
}
```

### Build Process
```json
{
    "scripts": {
        "build": "webpack --mode production",
        "dev": "webpack --mode development --watch",
        "test": "jest && phpunit",
        "lint": "eslint assets/js && phpcs includes/",
        "package": "npm run build && zip -r aicoso-wishlist.zip . -x node_modules/\\* .git/\\*"
    }
}
```

## Monitoring & Analytics

### Performance Monitoring
- Query execution time tracking
- Memory usage monitoring
- Cache hit/miss ratios
- AJAX response times

### Error Logging
```php
class Aicoso_Wishlist_Logger {
    public static function log($message, $level = 'info') {
        if (AICOSO_WISHLIST_DEBUG) {
            $log = sprintf('[%s] [%s] %s', 
                current_time('mysql'), 
                strtoupper($level), 
                $message
            );
            error_log($log, 3, AICOSO_WISHLIST_PLUGIN_DIR . 'logs/debug.log');
        }
    }
}
```

### Analytics Tracking
- Product popularity metrics
- User engagement statistics
- Conversion tracking
- Social sharing analytics

## Scalability Considerations

### Horizontal Scaling
- Database read replicas support
- CDN integration for static assets
- Session storage in external cache (Redis/Memcached)
- Load balancer compatibility

### Vertical Scaling
- Efficient database queries
- Optimized PHP code
- Minimal memory footprint
- Asynchronous processing for heavy operations

## Future Enhancements

### AI Integration
- Machine learning for product recommendations
- Predictive analytics for wishlist trends
- Natural language processing for wishlist search

### Advanced Features
- Real-time collaboration on wishlists
- Mobile app integration
- Voice assistant compatibility
- Blockchain-based wishlist verification

---

**Document Version**: 1.0.0  
**Last Updated**: 2024  
**Author**: Aicoso Development Team