SourceHub WordPress Plugin - Project Summary & Development History

Client Report - Last updated June 8, 2026

📘 For an actively-maintained developer onboarding document, see HANDOFF.md. This file is a high-level project summary suitable for client/stakeholder reporting. HANDOFF.md is the practical guide for any developer taking over the codebase.

Executive Summary

SourceHub is a comprehensive WordPress content syndication plugin that enables centralized editorial teams to distribute content across multiple WordPress sites (hub & spoke architecture) with full SEO integration, AI rewriting capabilities, and automated metadata synchronization.

Project Timeline

Project Start: July 2025
Client Handoff: September 29, 2025
Current Version: 2.4.2 (June 1, 2026)
Development Duration: ~11 months active development (July 2025 - June 2026)
Total Releases: 142 tagged releases
Total Commits: 203 commits

Code Metrics

Lines of Code (Custom Plugin Code - Excluding Libraries)

PHP Code: 22,691 lines
JavaScript: 5,108 lines
CSS: 3,861 lines
Documentation: 15+ markdown files (12 obsolete debug notes archived to docs/archive/ in June 2026)
Total Custom Code: 31,660 lines

Development Activity

Total Commits: 203
Tagged Releases: 142
Active Spokes in Production: 10 sites

Project Files

Total Project Files: 65+ files (PHP, JS, CSS, MD)
Core Plugin Files: 37 files/directories
Admin Interface Files: 7 major components
Include Files: 17 core classes

Major Version History

Version 2.4.x Series (Reliability hardening - 2026)

v2.4.2 (June 1, 2026) - Latest

Fixed duplicate hook registration causing 2× syndication jobs per save on WPEngine
Added static $initialized guards to Hub_Manager::init() and Spoke_Manager::init()
Resolved root cause of race_prevented entries on slow spokes (Williamson Source)
Eliminated last-write-wins content corruption from concurrent AI rewrites

v2.4.1 (May 26, 2026)

Fixed GitUpdater release detection (added Release Asset: true + Update URI headers)
Documented branch-install vs release-install gotcha in DEPLOYMENT.md

v2.4.0 (May 26, 2026) - Scheduled Posts Hardening

Multiple defenses against WP core auto-flipping future → publish when post_date_gmt was already in the past
Hub-side and spoke-side stale-future status guards
Spoke permalink now persisted and surfaced in syndication meta box "View" link
Fixed stuck-draft false positives (cron now skips drafts scheduled for the future)
Improved retry logic to preserve original scheduled time for future posts

Version 2.1.x - 2.3.x Series (Feature expansion, early 2026)

~3 releases (v2.1.0, v2.2.0, v2.3.0) focused on:

Messaging system between hub editors (Slack-like in-plugin chat)
Bug tracker improvements with email notifications
Activity log filtering, pagination, and export hardening
Auto-syndication rule engine refinements

Version 2.0.1.x - 2.0.2.x Series (Stabilization, late 2025 - early 2026)

~15 patch releases addressing:

Sync status race conditions on fast-completing spokes
Yoast meta save timing
Featured image metadata sync (title, alt, caption, description)
Gallery image processing
CORS handling for Local by Flywheel environments

Version 2.0.0.x Series (Production Ready - Late 2025)

v2.0.0.3 (December 15, 2025)

Activity Log timestamp improvements (full date/time display)
Publication storage reference documentation
Timezone conversion fixes

v2.0.0.2 (December 5, 2025)

Critical race condition fix for fast spoke completions
Pending completion flag optimization

v2.0.0.1 (December 5, 2025)

Duplicate publish protection with 10-second debounce
Multiple publish event handling

v2.0.0.0 (December 4, 2025) - MAJOR ARCHITECTURAL RELEASE

Complete migration from wp-cron to Action Scheduler
100% reliable async processing across all hosting environments
Eliminated all wp-cron dependencies
Consistent behavior on WP Engine, Local, and all hosting platforms

Version 1.9.x Series (Stability & Reliability Improvements)

70+ incremental releases focusing on:

Delayed sync reliability (v1.9.9.x series - 12 releases)
Race condition fixes
Lock collision resolution
Spoke completion tracking
Object cache optimization
WordPress cron diagnostics and fixes

Version 1.8.x Series (First Publish Fixes)

9 releases addressing:

Draft → publish transition handling
Auto-draft post processing
Status transition hooks
Spoke selection persistence

Version 1.7.x Series (Syndication Flow)

10 releases improving:

First publish syndication
Yoast meta timing
Double syndication prevention
Deployment automation

Version 1.6.x Series (Core Features)

8 releases adding:

Async syndication processing
Gallery image support
Yoast focus keyword sync
Shortcode preservation
Calendar improvements

Version 1.5.x Series (Performance & Reliability)

4 releases implementing:

Auto-retry system
Sync status tracking
Performance timing
Duplicate prevention

Version 1.4.x Series (Admin Features)

4 releases adding:

Bug Tracker with @mentions
Activity Logs pagination & filtering
Export functionality
Avatar integration

Version 1.2.x - 1.3.x Series (Foundation)

15+ releases establishing:

Git Updater integration
Calendar time display
Post format sync
Validation system
Role-based access control

Key Features Developed

Core Syndication Engine

✅ Hub & Spoke architecture
✅ Real-time content distribution
✅ Async processing with Action Scheduler
✅ Automatic retry logic
✅ Comprehensive error handling
✅ Lock-based concurrency control

Content Processing

✅ Featured image synchronization with metadata (title, alt, caption, description)
✅ Gallery image support
✅ Category and tag mapping
✅ Post format preservation
✅ Shortcode preservation
✅ Smart Links (internal link adaptation)
✅ Custom Smart Links (per-spoke URL mapping)

SEO Integration

✅ Full Yoast SEO metadata sync
✅ Focus keyword/keyphrase
✅ Meta title and description
✅ OG images and social metadata
✅ Canonical URLs
✅ Indexable data

AI Capabilities

✅ OpenAI GPT-4o Mini integration
✅ Automatic content rewriting
✅ Per-post AI override controls
✅ Quote preservation in rewrites
✅ Title and excerpt rewriting

Admin Interface

✅ Modern Material Design UI
✅ Real-time sync status tracking
✅ Connection management dashboard
✅ Activity logs with filtering & export
✅ Editorial calendar view
✅ Bug tracker with email notifications
✅ Comprehensive settings panels
✅ Role-based access control

Developer Features

✅ REST API endpoints
✅ Comprehensive logging system
✅ Git Updater support for automatic updates
✅ Action Scheduler integration
✅ Database optimization with indexes
✅ Deployment automation scripts

Major Technical Achievements

1. Async Processing Architecture (v2.0.0.0)

Challenge: WordPress wp-cron is unreliable on many hosting platforms (WP Engine, etc.) Solution: Migrated entire plugin to Action Scheduler (WooCommerce's battle-tested library) Impact: 100% reliable execution across all environments

2. Race Condition Resolution (v1.9.9.x - v2.0.0.2)

Challenge: Fast spokes completing before slow spokes caused sync failures Solution: Pre-populated sync status, proper completion tracking, pending flags Impact: Eliminated posts stuck in draft status

3. Yoast SEO Timing Issues (v1.6.x - v1.9.x)

Challenge: Yoast doesn't build indexables until second save Solution: Delayed sync with shutdown hooks and proper timing Impact: Complete Yoast metadata now syncs on first publish

4. Performance Optimization (v1.2.3)

Challenge: Activity Logs page loading in 21 seconds Solution: Fixed N+1 queries, added composite indexes, eliminated infinite loops Impact: Page load reduced to <1 second

5. Smart Links System (v1.0.2)

Challenge: Internal links break when content moves to different domains Solution: Custom TinyMCE integration with base URL + custom URL mapping Impact: Seamless internal link adaptation across spoke sites

Problem-Solving Highlights

Critical Issues Resolved

Duplicate Syndication - Debounce logic prevents multiple publish events
Lock Collisions - Proper lock timing and delayed sync scheduling
Object Cache Staleness - Force fresh database reads for sync status
Spoke Post ID Bug - Return actual post IDs instead of boolean true
CORS Issues - Converted AJAX to page reloads for Local by Flywheel compatibility
Validation Loop - Added static guards to prevent infinite initialization
Featured Image Metadata - Complete metadata sync (title, alt, caption, description)
Gallery Images - Draft-first approach for proper gallery processing
First Publish Failures - Multiple hooks to catch all publish scenarios
Connection Testing - Proper API key handling from form vs database

Hosting Environment Compatibility

✅ WP Engine (production)
✅ Local by Flywheel (development)
✅ Standard WordPress hosting
✅ Multisite networks
✅ All major PHP versions (7.4+)

Documentation Created

Technical Documentation

README.md - Plugin overview and setup
CHANGELOG.md - Complete version history (281 lines)
DEPLOYMENT.md - Deployment procedures
PUBLICATION_STORAGE_REFERENCE.md - Database integration guide
CONTRIBUTING.md - Development guidelines

Feature Documentation

SMART_LINKS_README.md - Smart Links feature guide
VALIDATION-SYSTEM.md - Content validation system
GIT-UPDATER-SETUP.md - Auto-update configuration
PLUGIN-ICON-GUIDE.md - Branding assets

Debug Documentation

activitylog.md - Activity log analysis (184KB)
logs.md - Comprehensive logging guide
PERFORMANCE-DEBUG.md - Performance optimization notes
DEBUG-CUSTOM-SMART-LINKS.md - Smart Links debugging
BUTTON-DEBUG-TEST.md - UI component testing
Multiple test and debug markdown files

Testing & Quality Assurance

Environments Tested

Local by Flywheel (development)
WP Engine (production)
Multiple WordPress versions (5.0 - 6.4)
PHP 7.4, 8.0, 8.1, 8.2

Test Scenarios Covered

First publish syndication
Update syndication
Scheduled post publishing
Multiple spoke sites (2-10+ spokes)
Fast vs slow spoke response times
Network failures and retries
Concurrent post saves
User role permissions
API authentication
Image processing
Yoast SEO integration
AI rewriting

Estimated Development Time

Based on commit history, version releases, and code complexity:

Phase 0: Initial Development & Prototyping (July - Sept 28, 2025)

~100 hours - Architecture design, initial plugin structure, core functionality development, testing

Database schema design
Hub & Spoke architecture planning
Initial syndication engine
Early testing and iteration
Pre-production development

Phase 1: Foundation & Client Handoff (Sept 29 - Oct 15, 2025)

~80 hours - Git repository initialization, refinement, database optimization, core syndication

Phase 2: Feature Development (Oct 16 - Nov 15, 2025)

~120 hours - Smart Links, AI integration, admin UI, calendar, bug tracker

Phase 3: Stability & Reliability (Nov 16 - Dec 4, 2025)

~100 hours - Race conditions, async processing, Action Scheduler migration

Phase 4: Polish & Production (Dec 5 - Dec 15, 2025)

~40 hours - Final bug fixes, documentation, timezone handling

Total Estimated Development Time: 440+ hours

This includes:

Architecture and design
Core development
Testing and debugging
Documentation
Client communication
Bug fixes and iterations

Current Status

Production Ready ✅

Version 2.4.2 deployed to main branch and live on hub2a.wpenginepowered.com + 10 spoke sites
Duplicate hook registration root cause resolved (June 2026)
Scheduled post premature-publish bug resolved (May 2026)
Developer handoff documentation completed (June 2026 — see HANDOFF.md)
Repo documentation cleaned: 12 obsolete debug notes archived to docs/archive/
Automated deployment pipeline established via GitUpdater + tagged releases

Active Features

✅ Hub & Spoke syndication
✅ Yoast SEO integration
✅ AI content rewriting
✅ Smart Links
✅ Activity logging
✅ Editorial calendar
✅ Bug tracker
✅ Role-based access
✅ Automatic updates via Git Updater

Known Limitations

Requires Action Scheduler library (included)
Yoast SEO plugin required for SEO features
OpenAI API key required for AI rewriting

Future Enhancement Opportunities

Potential Features (Not Currently Scoped)

Multi-language support (WPML integration)
Advanced scheduling rules
Content approval workflows
Analytics dashboard
Custom field mapping
Media library synchronization
Comment syndication
User synchronization
Bulk operations interface
REST API expansion for third-party integrations

Repository Information

GitHub: https://github.com/mikefreemantn/SourceHub
Current Branch: main
Latest Release: v2.4.2
License: GPL v2 or later
WordPress Compatibility: 5.0+
PHP Requirement: 7.4+
Production Hub: hub2a.wpenginepowered.com (WP Engine)
Production Spokes: 10 sites (Williamson, Sumner, Rutherford, Wilson, Robertson, Cannon, Davidson, Maury, Dickson, Cheatham)

Conclusion

SourceHub represents a comprehensive, production-ready WordPress content syndication solution. Across 11 months of active development (July 2025 - June 2026), the project has delivered 142 tagged releases, 31,000+ lines of custom code, and resolved a long list of complex technical challenges including async processing, race conditions on slow spokes, SEO timing issues, scheduled post status transitions, and the duplicate-hook-registration bug that took multiple weeks to diagnose in mid-2026.

The project demonstrates expertise in:

WordPress plugin architecture
Async processing and job queuing
REST API development
Database optimization
UI/UX design
SEO integration
AI/ML integration
DevOps and deployment automation
Technical documentation

Project Status: Production Ready & Ready for Developer Handoff

Original report: December 15, 2025 Updated: June 8, 2026 — v2.4.2, handoff-ready Developer: Mike Freeman - Man Over Machine Contact: https://manovermachine.com

FilesExpand file tree

PROJECT_SUMMARY.md

Latest commit

History