WP-Content-Sync/docs/superpowers/specs/2026-04-25-wordpress-content-sync-design.md

# WordPress Content Sync Plugin Design

**Date:** 2026-04-25
**Type:** Feature Design
**Status:** Approved

## Overview

A WordPress plugin that enables bidirectional content synchronization between two WordPress instances, supporting both REST API and file-based transfer methods. The plugin handles all content types including posts, pages, custom post types, taxonomies, and media, with automatic URL rewriting for domain changes.

## Use Case

Primary use case is syncing content between production and staging/development environments for developers building and maintaining WordPress sites. The plugin must work with instances that are not publicly accessible and where git or wp-cli are unavailable.

## Architecture

### Core Layers

**Core Sync Engine**
- Orchestrates sync operations between instances
- Manages both REST API and file transfer methods
- Coordinates source and destination operations
- Handles error recovery and retry logic

**Content Handlers**
- Separate modules for different content types
- Each handler extracts, transforms, and restores specific content
- Supports posts, pages, media, custom post types, taxonomies, metadata

**URL Transformation Layer**
- Handles all URL rewriting during sync operations
- Supports automatic domain mapping and manual overrides
- Processes content links, image paths, and custom field URLs

**Transport Layer**
- Abstracts communication method between instances
- REST API implementation with application password authentication
- File transfer implementation as fallback

**Admin Interface**
- WordPress admin pages for configuration
- Sync operation management and monitoring
- Status reporting and error handling

## Core Components

### Sync Manager
Central orchestrator responsible for:
- Managing sync configuration (instance pairs, credentials, URL mappings)
- Determining transport method (REST API vs file transfer)
- Coordinating content handlers during sync operations
- Handling error recovery and retry logic
- Providing sync status and progress reporting

### Content Handlers
Specialized processors for different content types:

**Posts/Pages Handler**
- Standard WordPress content with revisions
- Handles post content, excerpts, titles, and status
- Manages post relationships and hierarchy

**Media Handler**
- File uploads and attachments
- URL rewriting for media references
- Handles image sizes and metadata

**Custom Post Types Handler**
- Dynamic CPT support
- Respects CPT registration and capabilities
- Handles CPT-specific metadata

**Taxonomies Handler**
- Categories, tags, and custom taxonomies
- Term relationships and hierarchies
- Term metadata and descriptions

**Metadata Handler**
- Post meta, user meta, and options
- Serialized data handling
- Custom field URL scanning

**Users Handler** (Optional)
- User accounts and roles
- User capabilities and permissions
- User metadata

### URL Transformer
Handles URL transformation during sync:
- Domain mapping configuration (source → destination URLs)
- Content body URL replacement (links, images, embedded content)
- GUID and permalink updates
- Custom field URL scanning
- Serialized data URL replacement

### Transport Abstraction
Two implementation strategies:

**REST API Transport**
- Uses WordPress REST API endpoints
- Application password authentication
- Automatic when instances can communicate
- Supports real-time sync operations

**File Transport**
- Generates JSON packages with all content data
- Manual file transfer between instances
- Fallback when REST API unavailable
- Supports offline sync scenarios

## Data Flow

### Push Operation (Source → Destination)
1. User initiates push from source instance admin
2. Sync Manager validates destination connection
3. Content handlers extract data from source database
4. URL Transformer rewrites source URLs to destination URLs
5. Transport layer sends data (REST API or generates file)
6. Destination receives and processes data
7. Content handlers import/merge data on destination
8. Sync Manager reports completion status

### Pull Operation (Destination ← Source)
1. User initiates pull from destination instance admin
2. Destination connects to source instance
3. Source extracts and transforms data
4. Source sends data to destination
5. Destination processes and imports data
6. Sync Manager reports completion status

### File Transfer Flow
1. Source instance exports data to JSON file
2. User manually transfers file between instances
3. Destination instance imports JSON file
4. Same processing as REST API flow

### Conflict Resolution
- Last-write-wins strategy for content conflicts
- Optional merge strategies for specific content types
- Conflict log for review after sync operations
- User notification of conflicts requiring manual resolution

## Error Handling

### Connection Errors
- Automatic retry with exponential backoff for REST API failures
- Graceful fallback to file transfer if REST API unavailable
- Clear error messages with troubleshooting steps
- Connection timeout handling

### Data Validation
- Schema validation for imported JSON files
- Content integrity checks during sync operations
- Validation of required fields and relationships
- Data type and format verification

### Partial Failure Recovery
- Transaction-based sync operations with rollback on failure
- Progress tracking for resumable sync operations
- Detailed error logs with context for debugging
- State preservation for interrupted operations

### User-Facing Error Messages
- Specific error types (connection, authentication, data, transport)
- Actionable suggestions for each error type
- Error severity levels (warning, error, critical)
- Contextual help and documentation links

### Logging and Debugging
- Detailed sync operation logs
- Performance metrics for optimization
- Optional debug mode for troubleshooting
- Log rotation and management

## Admin Interface

### Main Dashboard
- List of configured sync pairs (source/destination instances)
- Quick sync status indicators (last sync time, success/failure)
- Push/Pull action buttons for each sync pair
- Sync history and logs viewer
- Overall system health indicators

### Configuration Pages

**Sync Pair Setup**
- Add/edit source and destination instances
- Instance naming and identification
- Connection details and credentials

**Connection Test**
- Verify REST API connectivity
- Test authentication credentials
- Validate URL mappings
- Network diagnostics

**URL Mapping Configuration**
- Define source/destination domain mappings
- Multiple domain support
- URL pattern matching
- Custom replacement rules

**Content Type Selection**
- Choose which content types to sync
- Individual content type toggles
- Bulk selection options
- Custom post type detection

**Authentication Setup**
- Application passwords and credentials
- Secure credential storage
- Credential rotation support
- Permission verification

### Sync Operation Interface
- Progress bar with real-time status updates
- Content type breakdown (posts, media, etc.)
- Error/warning notifications during sync
- Cancel operation support
- Detailed results summary after completion

### Settings and Preferences
- Default sync direction preferences
- Conflict resolution strategy selection
- Automatic URL replacement toggle
- Logging level configuration
- Performance tuning options

## Testing Strategy

### Unit Testing
- Content handler tests for each content type
- URL transformer tests with various URL patterns
- Transport layer tests for both REST API and file methods
- Sync manager orchestration tests
- Individual component isolation tests

### Integration Testing
- End-to-end sync operations between test instances
- REST API authentication and communication
- File export/import functionality
- URL rewriting accuracy across different content types
- Multi-instance sync scenarios

### Edge Case Testing
- Large content sets (performance testing)
- Special characters and encoding issues
- Custom post types and taxonomies
- Plugin/theme compatibility
- Network connectivity issues
- Concurrent sync operations

### Manual Testing Scenarios
- Production to staging sync
- Staging to production sync
- File transfer fallback
- URL replacement accuracy
- Conflict resolution behavior
- Error recovery procedures

## Technical Requirements

### WordPress Compatibility
- Minimum WordPress version: 5.6+
- PHP version: 7.4+
- REST API support required
- Application passwords feature required for REST API method

### Performance Considerations
- Support for large content sets (1000+ posts)
- Efficient memory usage during sync operations
- Background processing for long-running operations
- Progress tracking for user feedback

### Security Considerations
- Secure credential storage
- Application password authentication
- Data encryption for file transfers
- Permission validation
- Audit logging for sync operations

## Success Criteria

1. Successfully sync all content types between two WordPress instances
2. Handle URL rewriting accurately for domain changes
3. Support both REST API and file transfer methods
4. Provide clear error messages and recovery options
5. Work with non-publicly accessible instances
6. Function without git or wp-cli dependencies
7. Support bidirectional sync with push/pull operations
8. Handle custom post types and taxonomies dynamically
9. Provide comprehensive admin interface for configuration
10. Include robust error handling and logging