# Phase 3: Integration & Scale (Weeks 9-12)

## Overview
**Goal:** Integrate with translate-press-zone, enable WPML migration, scale to 10M+ posts  
**Duration:** 4 weeks  
**Prerequisites:** Phase 0, 1, and 2 complete

---

## Week 9: Plugin Abstraction Layer Implementation

### Context
From conversation (line 6073): "translate-press-zone should work with WPML, multilingual-press-zone, Polylang, AND TranslatePress"

### Task 9.1: Refactor translate-press-zone
**File:** `../translate-press-zone/includes/adapters/`

#### Sub-task 9.1.1: Create IMultilingualBridge Interface
- [ ] See PLUGIN-ABSTRACTION-LAYER.md for full interface definition
- [ ] Create `includes/interfaces/IMultilingualBridge.php`
- [ ] Define 12 core methods (get_active_languages, create_translation, etc.)

#### Sub-task 9.1.2: Refactor WPMLBridge → WPMLAdapter
- [ ] Rename class from `WPMLBridge` to `WPMLAdapter`
- [ ] Implement `IMultilingualBridge`
- [ ] Keep all existing WPML logic (zero functional changes)
- [ ] Update all 95 references in translate-press-zone codebase
- [ ] Test with existing WPML customers (zero breakage)

#### Sub-task 9.1.3: Create MPZAdapter
- [ ] File: `includes/adapters/MPZAdapter.php`
- [ ] Implement `IMultilingualBridge`
- [ ] Connect to `\MultilingualPressZone\Core\Plugin::instance()`
- [ ] Use direct DB access for performance (no WP Query overhead)
- [ ] Cache all language lookups
- [ ] Test: Create translation via MPZ, verify translate-press-zone can translate it

#### Sub-task 9.1.4: Create PolylangAdapter
- [ ] File: `includes/adapters/PolylangAdapter.php`
- [ ] Wrap Polylang functions: `pll_languages_list()`, `pll_get_post()`, etc.
- [ ] Handle Polylang's different data structures
- [ ] Test with Polylang Pro

#### Sub-task 9.1.5: Create BridgeFactory
- [ ] File: `includes/factories/BridgeFactory.php`
- [ ] Auto-detect which multilingual plugin is active
- [ ] Priority order: MPZ > WPML > Polylang > TranslatePress
- [ ] Singleton pattern with caching
- [ ] Return NullAdapter if no plugin detected

---

## Week 10: WPML Migration Tools

### Context
From conversation (line 5921): "Enterprise customers need confidence in migration path from WPML to MPZ"

### Task 10.1: Migration Architecture
**File:** `includes/Core/WPMLMigrator.php`

#### Sub-task 10.1.1: Data Mapping Strategy
**WPML Tables → MPZ Tables:**
```sql
-- Languages
wp_icl_languages → wp_mpz_languages
(active, code, default_locale) → (is_active, code, locale)

-- Translations
wp_icl_translations → wp_mpz_translations
(trid, element_id, element_type, language_code, source_language_code)
→ (translation_group_id, element_id, element_type, language_code, source_element_id)

-- String Translations
wp_icl_strings → wp_mpz_string_translations
(name, value, language, context) → (string_key, original_string, language_code, context)
```

#### Sub-task 10.1.2: Chunked Processing Engine
- [ ] Process 1000 posts per batch (prevent timeouts)
- [ ] Store progress in wp_options: `mpz_migration_progress`
- [ ] Resume capability if migration interrupted
- [ ] Dry-run mode (no writes, just validation)
- [ ] Rollback capability (restore from backup)

#### Sub-task 10.1.3: Migration Wizard UI
**File:** `admin/views/migration-wizard.php`

**Steps:**
1. **Pre-flight Check**
   - Verify WPML installed and active
   - Check database size
   - Estimate migration time (100K posts = ~30 minutes)
   - Check disk space for backup
   - Show warnings if any issues

2. **Backup**
   - Create full database backup
   - Store in wp-content/uploads/mpz-backups/backup-{timestamp}.sql
   - Show backup file size and location
   - Verify backup integrity (test restore on sample)

3. **Migration**
   - Progress bar (0-100%)
   - Live log feed showing progress
   - ETA calculation
   - Pause/Resume buttons
   - Cancel with rollback option

4. **Verification**
   - Compare translation counts: WPML vs MPZ
   - Verify language settings match
   - Validate translation relationships
   - Test 100 random posts

5. **Completion**
   - Migration summary report
   - Option to deactivate WPML (keep for 7 days)
   - Rollback instructions (if needed within 7 days)
   - Performance comparison: Before vs After

#### Sub-task 10.1.4: Performance Optimization
- [ ] Use direct SQL INSERTs (bypass wp_insert_post for speed)
- [ ] Disable post hooks during migration (re-enable after)
- [ ] Increase PHP memory limit temporarily
- [ ] Disable object cache writes during migration
- [ ] Batch cache invalidation (not per-item)

**Target Performance:**
- 500K posts in < 1 hour
- 1M posts in < 2 hours
- Memory usage < 512MB
- CPU usage < 50%

---

## Week 11: Database Partitioning & Optimization

### Context
From conversation (line 5198): "Handle 10M+ posts efficiently"

### Task 11.1: Table Partitioning Strategy

#### Sub-task 11.1.1: Partition Translations Table
```sql
-- Partition by element_type (post, page, product, term)
ALTER TABLE wp_mpz_translations
PARTITION BY LIST(element_type) (
    PARTITION p_post VALUES IN ('post'),
    PARTITION p_page VALUES IN ('page'),
    PARTITION p_product VALUES IN ('product'),
    PARTITION p_term VALUES IN ('term'),
    PARTITION p_other VALUES IN (DEFAULT)
);
```

**Benefits:**
- Queries filtered by element_type only scan relevant partition
- 4x faster for typical queries (post translations)
- Easier to maintain (archive old posts partition)

#### Sub-task 11.1.2: Partition Workflow History
```sql
-- Partition by month (for archival)
ALTER TABLE wp_mpz_workflow_history
PARTITION BY RANGE (YEAR(created_at) * 100 + MONTH(created_at)) (
    PARTITION p_202601 VALUES LESS THAN (202602),
    PARTITION p_202602 VALUES LESS THAN (202603),
    PARTITION p_202603 VALUES LESS THAN (202604),
    -- Auto-generate partitions for next 12 months
);
```

**Benefits:**
- Old history can be archived/compressed
- Recent queries are faster (only scan current partition)
- Disk space savings (compress old partitions)

### Task 11.2: Read Replica Support
**File:** `includes/Core/DatabasePool.php`

#### Sub-task 11.2.1: Connection Pool Implementation
- [ ] Separate connections for reads vs writes
- [ ] Load balance reads across replicas (round-robin)
- [ ] Fallback to primary if replica unavailable
- [ ] Health checks every 30 seconds
- [ ] Configuration: `define('MPZ_REPLICA_HOSTS', ['replica1.db', 'replica2.db']);`

#### Sub-task 11.2.2: Query Routing
- [ ] All SELECT queries → replicas
- [ ] All INSERT/UPDATE/DELETE → primary
- [ ] Transaction blocks → always primary
- [ ] Cache writes → async to replicas (eventual consistency OK)

### Task 11.3: Query Optimization Audit
**File:** `includes/Core/QueryOptimizer.php`

#### Sub-task 11.3.1: Slow Query Analysis
- [ ] Enable MySQL slow query log (queries > 100ms)
- [ ] Analyze top 20 slowest queries
- [ ] Add missing indexes
- [ ] Rewrite inefficient queries
- [ ] Document optimizations in PERFORMANCE-OPTIMIZATIONS.md

#### Sub-task 11.3.2: Covering Index Creation
```sql
-- Covering index for common translation lookup
CREATE INDEX idx_translation_lookup 
ON wp_mpz_translations (element_type, language_code, element_id) 
INCLUDE (translation_group_id, source_element_id, translation_status);
```

**Benefit:** Query can be satisfied entirely from index (no table access)

---

## Week 12: Load Testing & Performance Validation

### Context
From conversation (line 5198): "Prove 10-100x faster than WPML"

### Task 12.1: Test Environment Setup
**Requirements:**
- 10M posts, 10 languages (100M translation records)
- Dedicated test server: 16 CPU, 64GB RAM, NVMe SSD
- Production-like data: real post content, images, taxonomies
- Monitoring: New Relic or Datadog

#### Sub-task 12.1.1: Data Generation
- [ ] Use WP-CLI to generate test posts
- [ ] Script: `wp mpz generate-test-data --posts=10000000 --languages=10`
- [ ] Distribute evenly across languages
- [ ] Include realistic content (Lorem Ipsum + real HTML)
- [ ] Add taxonomy terms, featured images, meta data

#### Sub-task 12.1.2: WPML Baseline
- [ ] Install WPML on identical test environment
- [ ] Import same 10M posts
- [ ] Run benchmark suite
- [ ] Record metrics: page load time, memory, queries

### Task 12.2: Load Testing Scenarios
**Tool:** k6 (load testing framework)

#### Scenario 1: Home Page Load (Language Switcher)
```javascript
import http from 'k6/http';
export default function() {
  http.get('https://test.site.com/'); // Loads language switcher
}
```
**Test:**
- 1000 concurrent users
- Duration: 5 minutes
- Target: < 50ms MPZ overhead

#### Scenario 2: Post Translation Lookup
```javascript
export default function() {
  http.get('https://test.site.com/es/sample-post-123/'); // Spanish version
}
```
**Test:**
- 5000 concurrent users
- Duration: 10 minutes
- Target: < 100ms translation lookup

#### Scenario 3: Language Switch
```javascript
export default function() {
  http.post('https://test.site.com/wp-admin/admin-ajax.php', {
    action: 'mpz_switch_language',
    language: 'fr'
  });
}
```
**Test:**
- 500 concurrent users
- Duration: 2 minutes
- Target: < 100ms switch time

#### Scenario 4: Sustained Load (24 Hours)
```javascript
export default function() {
  const pages = ['/', '/en/about/', '/es/blog/', '/fr/products/'];
  const page = pages[Math.floor(Math.random() * pages.length)];
  http.get(`https://test.site.com${page}`);
}
```
**Test:**
- 200 constant concurrent users
- Duration: 24 hours
- Target: No memory leaks, stable response times

### Task 12.3: Performance Metrics Collection

#### Metrics to Track:
1. **Page Load Overhead**
   - WPML: 500-2000ms
   - MPZ Target: < 50ms
   - Measurement: Time to execute language detection + translation lookup

2. **Database Queries Per Page**
   - WPML: 50-200 queries
   - MPZ Target: < 5 queries
   - Measurement: WordPress Query Monitor plugin

3. **Memory Usage**
   - WPML: 256-512MB per request
   - MPZ Target: < 128MB per request
   - Measurement: memory_get_peak_usage()

4. **Cache Hit Ratio**
   - MPZ Target: > 80%
   - Measurement: CacheManager::get_stats()

5. **Translation Lookup Speed**
   - WPML: 200-500ms (post meta queries)
   - MPZ Target: < 10ms (indexed table query)
   - Measurement: Query execution time

### Task 12.4: Performance Report Generation
**File:** `PERFORMANCE-BENCHMARKS.md`

#### Report Sections:
1. **Test Environment Specs**
2. **Data Set Characteristics** (10M posts, 10 languages)
3. **Baseline Metrics** (WPML performance)
4. **MPZ Metrics** (our performance)
5. **Comparison Table** (WPML vs MPZ)
6. **Performance Gains** (10x, 50x, 100x where achieved)
7. **Bottleneck Analysis** (remaining slow queries)
8. **Optimization Recommendations** (future improvements)
9. **Customer-Facing Summary** (for marketing)

#### Example Comparison Table:
| Metric | WPML | MPZ | Improvement |
|--------|------|-----|-------------|
| Page load overhead | 850ms | 42ms | **20x faster** |
| Queries per page | 127 | 3 | **42x fewer** |
| Memory per request | 384MB | 96MB | **4x less** |
| Language switch | 2.1s | 87ms | **24x faster** |
| Translation lookup | 340ms | 8ms | **42x faster** |

### Task 12.5: Stress Testing
**Objective:** Find breaking point

#### Test 1: Maximum Concurrent Users
- Gradually increase from 1000 to 10,000 concurrent users
- Find point where response time exceeds 500ms
- Record maximum throughput (requests/sec)

#### Test 2: Maximum Database Size
- Test with 50M, 100M, 500M translation records
- Measure query performance degradation
- Identify scaling limits

#### Test 3: Memory Leak Detection
- Run for 7 days under moderate load
- Monitor memory usage trends
- Check for gradual memory growth

---

## Phase 3 Deliverables

### Technical Deliverables:
- [ ] translate-press-zone refactored with plugin abstraction layer
- [ ] MPZAdapter, PolylangAdapter implemented
- [ ] WPML migration tool with wizard UI
- [ ] Database partitioning implemented
- [ ] Read replica support added
- [ ] Load testing suite (4 scenarios)
- [ ] Performance benchmarks report

### Documentation Deliverables:
- [ ] WPML-MIGRATION-GUIDE.md (user-facing)
- [ ] PERFORMANCE-BENCHMARKS.md (marketing material)
- [ ] PERFORMANCE-OPTIMIZATIONS.md (technical)
- [ ] API compatibility matrix (WPML vs MPZ functions)

### Success Criteria:
- [ ] translate-press-zone works with MPZ, WPML, and Polylang
- [ ] WPML migration completes 500K posts in < 1 hour
- [ ] MPZ handles 10M posts with < 50ms overhead
- [ ] Database queries < 5 per page
- [ ] Memory usage < 128MB per request
- [ ] Cache hit ratio > 80%
- [ ] Performance 10-100x better than WPML (proven in benchmarks)
- [ ] Zero data loss in migration (verified with test data)

---

## Next Phase
→ [PHASE4-LAUNCH-POLISH.md](./PHASE4-LAUNCH-POLISH.md)