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