Overview

Purpose and Scope

This page provides a high-level introduction to the AJC Bridge plugin, explaining its purpose, architecture, and core concepts. For detailed explanations of specific subsystems, see:

• Publishing strategies and configuration → Publishing Strategies
• Detailed architecture and component interactions → Architecture
• Individual component documentation → Sections 2-7

What is AJC Bridge?

AJC Bridge is a WordPress plugin that transforms WordPress into a flexible content management system for multi-channel publishing. It enables content creators to write in WordPress while automatically synchronizing content to:

• Static site generators (Hugo, Astro, Jekyll) hosted on GitHub Pages
• Developer platforms (dev.to) for community engagement
• Headless WordPress deployments with automatic redirects

The plugin solves the problem of maintaining content across multiple platforms by providing a single source of truth (WordPress) with automated, reliable synchronization to external destinations.

Key Capabilities:

• Automated Markdown conversion from WordPress HTML
• Image optimization (WebP/AVIF generation)
• Atomic Git commits via GitHub Trees API
• Async background processing to avoid blocking requests
• Per-post syndication control
• Comprehensive error handling and retry logic

Sources: README.md1-162 readme.txt1-79 ajc-bridge.php1-14

System Context

The following diagram shows how AJC Bridge sits between WordPress and external services:

System Context Diagram

Sources: README.md11-13 readme.txt11-23

Core Architecture

AJC Bridge follows a layered architecture with clear separation of concerns. The following diagram shows the major components using actual class names from the codebase:

Component Architecture Diagram

Component Roles:

Component	Class	Responsibility
Plugin	Plugin	Singleton bootstrap, WordPress hooks registration
Queue Manager	Queue_Manager	Async task scheduling via Action Scheduler
Sync Runner	Sync_Runner	Central orchestrator, strategy routing
Hugo Adapter	Hugo_Adapter	Convert content to Hugo-compatible Markdown
Astro Adapter	Astro_Adapter	Convert content to Astro MDX format
DevTo Adapter	DevTo_Adapter	Convert content to dev.to Markdown
Media Processor	Media_Processor	Image extraction and WebP/AVIF generation
Git API	Git_API	GitHub REST API client for atomic commits
DevTo API	DevTo_API	dev.to (Forem) REST API client
Logger	Logger	Centralized logging to files and database
Settings	Settings	Configuration UI and credential management
Columns	Columns	Post list sync status display
Post Meta Box	Post_Meta_Box	Per-post syndication controls
Headless Redirect	Headless_Redirect	301 redirects for headless modes

Sources: ajc-bridge.php158-161 README.md449-541

Publishing Strategies

AJC Bridge supports five distinct publishing strategies, each optimized for different workflows:

Strategy Overview Diagram

Strategy Selection:

The publishing strategy is stored in wp_options as ajc_bridge_settings['publishing_strategy'] and determines:

1. Which adapters execute during sync operations
2. Whether frontend redirects activate (headless modes)
3. Canonical URL handling for SEO
4. Per-post control availability (dev.to checkbox visibility)

For detailed strategy explanations and use cases, see Publishing Strategies.

Sources: readme.txt17-24 README.md79-86

Key Data Structures

Post Meta Keys:

The plugin uses WordPress post meta to track synchronization state:

Meta Key	Type	Purpose
_ajc_sync_status	string	Current state: pending, processing, synced, failed
_ajc_sync_last	timestamp	Unix timestamp of last successful sync
_ajc_file_path	string	GitHub file path (e.g., content/posts/2024-01-15-hello.md)
_ajc_last_commit_url	string	Full URL to GitHub commit
_ajc_retry_count	int	Number of sync retry attempts (max 3)
_ajc_bridge_publish_devto	bool	Per-post dev.to syndication flag
_ajc_bridge_devto_id	int	dev.to article ID for updates
_ajc_bridge_devto_url	string	Published dev.to article URL
_wpjamstack_lock	bool	Sync operation lock with 60s expiration

Settings Structure:

Configuration stored in wp_options as ajc_bridge_settings:

Sources: README.md602-626

Sync Flow Overview

The following diagram illustrates the high-level synchronization flow from post publication to external deployment:

Basic Sync Flow

Key Flow Characteristics:

1. Non-blocking: User actions return immediately; sync happens in background
2. Lock-based concurrency control: Prevents simultaneous syncs of same post
3. Status tracking: Post meta provides real-time visibility
4. Retry mechanism: Failed syncs automatically retry up to 3 times
5. Delegated processing: Queue_Manager handles scheduling, Sync_Runner handles business logic

Sources: README.md544-570

Integration Points

WordPress Hooks

The plugin integrates with WordPress through standard action and filter hooks:

Action Hooks:

Hook	Handler	Purpose
save_post	Plugin::handle_save_post()	Enqueue sync when post published/updated
wp_trash_post	Plugin::handle_trash_post()	Delete content from external platforms
deleted_post	Plugin::handle_deleted_post()	Cleanup when post permanently deleted
admin_menu	Admin::register_menu()	Register admin pages
template_redirect	Headless_Redirect::maybe_redirect()	Handle frontend redirects (headless mode)
admin_enqueue_scripts	Settings::enqueue_assets()	Load admin CSS/JS

AJAX Actions:

Action	Handler	Purpose
wp_ajax_ajc_bridge_sync_now	Columns::ajax_sync_now()	Manual post sync from admin
wp_ajax_ajc_bridge_test_github	Settings::ajax_test_github()	Test GitHub API connection
wp_ajax_ajc_bridge_test_devto	Settings::ajax_test_devto()	Test dev.to API connection

Sources: ajc-bridge.php158-161

External APIs

GitHub REST API:

• Endpoint Base: https://api.github.com
• Authentication: Personal Access Token (PAT) via Authorization: token {token} header
• Key Operations:
  • POST /repos/{owner}/{repo}/git/blobs - Upload file content
  • POST /repos/{owner}/{repo}/git/trees - Create tree structure
  • POST /repos/{owner}/{repo}/git/commits - Create commit
  • PATCH /repos/{owner}/{repo}/git/refs/heads/{branch} - Update branch reference
  • DELETE /repos/{owner}/{repo}/contents/{path} - Delete files

dev.to (Forem) API:

• Endpoint Base: https://dev.to/api
• Authentication: API Key via api-key: {key} header
• Key Operations:
  • POST /api/articles - Create new article
  • PUT /api/articles/{id} - Update existing article
  • GET /api/articles/me - List user's articles

All HTTP requests use WordPress's wp_remote_request() function for compatibility.

Sources: README.md449-541

Deployment Architecture

Plugin Distribution:

The plugin is distributed as a ZIP file (ajc-bridge.zip) containing:

• PHP source files with PSR-4 autoloading
• Composer dependencies (vendor/ directory)
• Admin UI assets (CSS/JS)
• Plugin update checker library

Installation Methods:

1. WordPress Admin Upload - Upload ZIP via Plugins → Add New
2. Manual FTP - Extract to wp-content/plugins/ajc-bridge/
3. Git Clone - Developer installation with composer install

Auto-Update System:

The plugin includes a GitHub-based update checker (ajc-bridge.php20-32) that:

• Checks for new releases on GitHub
• Displays update notifications in WordPress admin
• Enables one-click updates without WordPress.org

Sources: ajc-bridge.php1-162 README.md131-142

Technical Requirements

System Requirements:

Requirement	Minimum	Recommended
WordPress	6.9+	Latest stable
PHP	8.1+	8.2+
MySQL/MariaDB	5.7+ / 10.2+	Latest stable
Web Server	Apache 2.4 / Nginx 1.18	Latest stable

PHP Extensions:

Extension	Required	Purpose
json	✓	API communication
curl	✓	HTTP requests
openssl	✓	Token encryption
imagick	✗	Image optimization (AVIF support)
gd	✗	Image optimization (fallback)
mbstring	✗	Character encoding

WordPress Configuration:

• Action Scheduler must be functional (not blocked by hosting)
• wp-cron.php should run regularly (or system cron configured)
• Sufficient max_execution_time for image processing (60s+ recommended)
• Write permissions on wp-content/uploads/ directory

Sources: readme.txt70-77 ajc-bridge.php106-121

Security Model

Credential Storage:

• GitHub tokens encrypted using AES-256-CBC with WordPress salts
• Encryption key derived from wp_salt('auth') and wp_salt('nonce')
• Tokens masked in UI as ghp_***...***
• Never logged or exposed in error messages

Access Control:

• Settings page requires manage_options capability (Administrator only)
• Sync operations require edit_posts capability (Author, Editor, Administrator)
• Authors can only sync their own posts
• AJAX actions protected with nonce verification

Input Sanitization:

• All user inputs sanitized via WordPress functions (sanitize_text_field(), esc_url(), etc.)
• GitHub repository format validated with regex
• File paths validated to prevent directory traversal

Sources: readme.txt228-232

Performance Characteristics

Async Processing:

• All sync operations run via Action Scheduler (WooCommerce library)
• No blocking on user actions (publish, update, delete)
• Batch processing with configurable concurrency
• Automatic retry with exponential backoff

API Optimization:

• GitHub Trees API reduces commits by ~70% vs. file-by-file uploads
• Single atomic commit for Markdown + all images
• Image processing uses temporary storage with guaranteed cleanup
• Connection pooling via persistent WP_Http instance

Caching:

• Post meta cached by WordPress's object cache
• Settings cached in memory during request lifecycle
• Transient-based locks with automatic expiration (60s)

Sources: README.md103-109 readme.txt61

Extension Points

The plugin provides several extension mechanisms for developers:

Filters:

Custom Adapters:

Developers can create custom adapters by implementing Adapter_Interface:

Sources: README.md981-985

Monitoring and Observability

Logging System:

• Logs stored in wp-content/uploads/ajc-bridge-logs/
• Daily log rotation with ISO 8601 date format
• Log levels: Info, Success, Warning, Error
• Debug mode for verbose logging
• Real-time log display in admin UI

Sync Status Tracking:

• Post list columns show sync status with icons
• Individual post meta boxes display detailed sync info
• Sync history page with filtering and search
• Bulk operations statistics

Action Scheduler Integration:

• View scheduled/completed/failed tasks
• Per-task execution logs
• Manual task re-execution
• Cleanup of old task records

Sources: README.md103-109 readme.txt225-227

Next Steps

For detailed information about specific aspects of the plugin:

• Publishing Strategies - Detailed strategy explanations → Publishing Strategies
• Architecture Deep-Dive - Component interactions and data flow → Architecture
• Sync Pipeline - Complete synchronization workflow → Sync Pipeline
• Content Adapters - SSG-specific conversion logic → Content Adapters
• External API Clients - GitHub and dev.to integration → External API Clients
• Admin Interface - Configuration and monitoring UI → Admin Interface
• Development Guide - Contributing and customization → Development Guide

Sources: README.md1-162