Architecture

Architecture Overview

The Elasticsearch integration follows a clean separation of concerns with three main layers, each handling specific responsibilities while maintaining loose coupling and high cohesion.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    User Interface Layer                     │
├─────────────────────┬─────────────────────┬─────────────────┤
│   Search Page       │  Monitoring Console │   Admin Panel   │
│ (page-search.php)   │ (console.php)       │ (WordPress)     │
└─────────────────────┴─────────────────────┴─────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                   WordPress Integration                     │
├─────────────────────┬─────────────────────┬─────────────────┤
│  AJAX Handlers      │  Template System    │  Hook System    │
│ (functions.php)     │ (page templates)    │ (WordPress)     │
└─────────────────────┴─────────────────────┴─────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                   Business Logic Layer                     │
├─────────────────────┬─────────────────────┬─────────────────┤
│  Elasticsearch      │  Console Manager    │  Sync Manager   │
│  Client             │ (Display Only)      │ (CLI/Cron)     │
└─────────────────────┴─────────────────────┴─────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                     Data Storage Layer                     │
├─────────────────────┬─────────────────────────────────────────┤
│   PostgreSQL        │           Elasticsearch               │
│   (Source Data)     │         (Search Index)                │
└─────────────────────┴─────────────────────────────────────────┘

Layer Responsibilities

User Interface Layer

Purpose: Present data and handle user interactions

Components:

• Search Page (page-search.php): Public-facing search interface
• Monitoring Console (page-elasticsearch-console.php): Admin dashboard
• WordPress Admin: Native WordPress admin integration

Key Features:

• Responsive design with mobile support
• Real-time AJAX interactions
• Progressive enhancement
• Accessibility compliance

WordPress Integration Layer

Purpose: Bridge between WordPress and business logic

Components:

• AJAX Handlers: Dynamic frontend interactions
• Template System: Page templates and components
• Hook System: WordPress hooks and filters

Key Features:

• Nonce-based security
• User permission validation
• WordPress coding standards
• Plugin compatibility

Business Logic Layer

Purpose: Core functionality and data processing

Components:

• Elasticsearch Client: Low-level ES operations
• Console Manager: Display and monitoring (WordPress context)
• Sync Manager: Data synchronization (CLI/cron context)

Key Features:

• Clean separation of concerns
• Error handling and recovery
• State management
• Performance optimization

Data Storage Layer

Purpose: Persistent data storage and retrieval

Components:

• PostgreSQL: Source data and metadata
• Elasticsearch: Search index and analytics

Key Features:

• ACID compliance (PostgreSQL)
• High availability (Elasticsearch)
• Data consistency
• Backup and recovery

Design Patterns

1. Separation of Concerns

CLI/Cron Operations vs WordPress Display Operations:

// CLI/Cron Context (scripts/elasticsearch-auto-sync.php)
class ElasticsearchAutoSyncManager {
    // Handles actual sync operations
    public function autoSync() { /* ... */ }
}

// WordPress Context (inc/elasticsearch-console-manager.php)
class ElasticsearchConsoleManager {
    // Display-only operations, safe for web context
    public function getStats() { /* ... */ }
}

2. State Management Pattern

JSON State Persistence for resumable operations:

// State file structure
{
  "phase": "bulk_syncing",
  "index_created": true,
  "total_products": 60560,
  "processed_products": 15000,
  "last_processed_id": 75981,
  "started_at": "2025-09-28T15:14:03+00:00",
  "last_run": "2025-09-28T16:22:53+00:00",
  "errors": [],
  "consecutive_failures": 0,
  "failed_batches": {}
}

3. Batch Processing Pattern

Configurable batch sizes with memory management:

class BatchProcessor {
    private $batch_size = 500;
    private $memory_limit = '256M';

    public function processBatch($items) {
        // Process items in configurable batches
        // Memory management and garbage collection
    }
}

4. Error Recovery Pattern

Failed batch tracking and automatic skipping:

class ErrorRecovery {
    private $max_failures = 3;
    private $failed_batches = [];

    public function handleFailedBatch($batch_id, $error) {
        // Track failures and skip after max attempts
    }
}

Data Flow Architecture

Search Request Flow

User Query → WordPress Template → AJAX Handler → Elasticsearch Client → ES Server
     ↓
Results Processing → Template Rendering → User Display

Synchronization Flow

Cron Trigger → Sync Manager → Database Query → Data Transform → Bulk Index → State Update
     ↓
Progress Tracking → Log Generation → Console Update

Monitoring Flow

Console Request → Console Manager → State File Read → Statistics Calculation → Display
     ↓
Real-time Updates → AJAX Refresh → User Interface

Component Interactions

Elasticsearch Client ↔ Database

// Database provides source data
$products = get_products_for_sync($batch_size);

// Transform for Elasticsearch
$es_documents = transform_products_for_elasticsearch($products);

// Bulk index to Elasticsearch
$result = $elasticsearch->bulkIndexProducts($es_documents);

// Update database sync status
mark_products_as_indexed($products);

Console Manager ↔ Sync Manager

// Console reads state (display only)
$state = $console_manager->getSyncState();

// Sync manager updates state (CLI only)
$sync_manager->updateSyncState($new_state);

WordPress ↔ Business Logic

// WordPress AJAX handler
add_action('wp_ajax_get_elasticsearch_stats', function() {
    $console_manager = new ElasticsearchConsoleManager();
    $stats = $console_manager->getStats();
    wp_send_json_success($stats);
});

Security Architecture

Access Control

// WordPress capability check
if (!current_user_can('manage_options')) {
    wp_die('Insufficient permissions');
}

// AJAX nonce verification
check_ajax_referer('elasticsearch_nonce', 'nonce');

Data Validation

// Input sanitization
$query = sanitize_text_field($_GET['q']);
$filters = array_map('sanitize_text_field', $_GET['filters']);

// SQL injection prevention
$result = pg_query_params($connection, $query, $params);

Error Information

// Client-side: Generic error messages
wp_send_json_error('Search temporarily unavailable');

// Server-side: Detailed logging
error_log("Elasticsearch error: " . $detailed_error);

Performance Architecture

Caching Strategy

// WordPress object cache
$cached_results = wp_cache_get($cache_key);
if ($cached_results === false) {
    $results = $elasticsearch->search($query);
    wp_cache_set($cache_key, $results, '', 300); // 5 min cache
}

Connection Management

// Connection pooling
class ConnectionManager {
    private static $connections = [];

    public static function getConnection($type) {
        // Reuse existing connections
        // Automatic reconnection on failure
    }
}

Memory Management

// Batch processing with memory limits
ini_set('memory_limit', '512M');
set_time_limit(300);

// Garbage collection
gc_collect_cycles();

Scalability Considerations

Horizontal Scaling

• Multiple Elasticsearch Nodes: Cluster configuration
• Load Balancing: Distribute search requests
• Database Replication: Read replicas for reporting

Vertical Scaling

• Memory Optimization: Increase PHP memory limits
• CPU Optimization: Parallel processing where possible
• Storage Optimization: SSD storage for better I/O

Monitoring & Alerting

• Performance Metrics: Response times, throughput
• Error Rates: Failed requests, sync failures
• Resource Usage: Memory, CPU, disk space

Next Steps

• Core Components - Detailed component analysis
• Database Integration - PostgreSQL integration
• WordPress Integration - WordPress-specific features
• Search Functionality - Search implementation