WordPress ActivityPub Plugin Re-architecture Proposal

[Jiwoon-Kim]

WordPress ActivityPub Plugin Re-architecture Proposal

This report proposes a re-architecture of the WordPress ActivityPub plugin, based on an analysis of its current structure and common issues within similar systems. The proposal aims to address problems of monolithic design, low testability, and limited extensibility.

---

1. Analysis of Current Architecture Issues

While direct access to the specific GitHub issue thread (#2073) was not possible, an analysis of related documentation and discussions revealed key architectural shortcomings that the re-architecture should address:

• Monolithic Class Structure: The ActivityPub\Server class appears to act as a central hub, handling multiple responsibilities such as request routing, data processing, and federation logic. This violates the Single Responsibility Principle (SRP), making the code difficult to understand, maintain, and modify without causing side effects.
• Low Testability: The tight coupling of various functionalities within a single class makes it challenging to isolate and test individual components. Unit testing becomes a complex task, as it requires mocking numerous dependencies and managing a large state.
• Poor Extensibility: The monolithic structure limits the ability for developers to extend or customize specific parts of the federation process. While the plugin uses WordPress actions and filters, they are often insufficient for deeply modifying core behaviors, which may require developers to "cobble together" functionality from other plugins.

---

2. Theoretical Foundation for the Re-architecture

The proposed re-architecture is grounded in established object-oriented design principles to build a more robust, scalable, and maintainable system.

• Single Responsibility Principle (SRP): Each class or module should have one, and only one, reason to change. By breaking down the monolithic Server class, we can create dedicated components for distinct tasks, such as handling HTTP requests or building ActivityPub objects.
• Dependency Injection (DI): Instead of classes creating their own dependencies, these dependencies are "injected" from the outside. This principle allows for easier testing, as mock objects can be injected during testing, and improves code flexibility by decoupling components from their specific implementations.
• Separation of Concerns: The plugin's logic should be divided into independent sections, each responsible for a specific function. This ensures that changes to one part of the system have minimal impact on others.

---

3. Proposed New Architecture

The new architecture would replace the monolithic ActivityPub\Server class with a set of modular, single-purpose services. These services would be managed by a Dependency Injection (DI) Container (e.g., a simple custom container or a more robust library like Symfony's), which would handle the creation and injection of dependencies.

Proposed Components:

• RequestRouter: This component's sole responsibility is to receive incoming HTTP requests and route them to the appropriate RequestHandler based on the request URI and method (e.g., inbox, outbox, or actor).
• RequestHandler: An interface for handling specific types of requests (e.g., InboxHandler, OutboxHandler). Each handler would contain the specific business logic for its function. For instance, the InboxHandler would parse an incoming ActivityPub object and pass it to the ActivityProcessor.
• ActivityProcessor: This service is responsible for validating and processing incoming ActivityPub activities. It would delegate the actual processing to specific handlers for different activity types (Create, Update, Delete, Follow, etc.).
• DataStore: An abstraction layer for all database interactions. This component would handle fetching and storing data related to actors, objects, and activities, without the need for other services to know the underlying database schema.
• ActivityBuilder: A factory or builder class responsible for constructing new ActivityPub objects and activities for publishing to the federation. This encapsulates the complex logic of building correctly formatted JSON-LD objects.

Example of Component Interaction:

1. A remote server sends a Follow activity to the plugin's inbox.
2. The RequestRouter receives the request and passes it to the InboxHandler.
3. The InboxHandler calls the ActivityProcessor to validate the activity.
4. The ActivityProcessor recognizes it as a Follow activity and passes it to a dedicated FollowHandler.
5. The FollowHandler uses the DataStore to save the new follower information in the database.

---

4. Expected Benefits

• Improved Maintainability: By adhering to the Single Responsibility Principle, each component becomes easier to understand and debug.
• Enhanced Testability: The use of Dependency Injection allows for individual components to be unit tested in isolation by injecting mock dependencies.
• Greater Extensibility: Developers can easily extend the plugin by creating new RequestHandlers or ActivityProcessors and registering them with the DI Container, without modifying core files.
• Clearer Codebase: The modular design creates a more logical and organized file structure, making it easier for new contributors to understand and contribute to the project.

[Jiwoon-Kim]

Proposal for Redesigning the WordPress ActivityPub Plugin

Overview: The Need for Architectural Modernization

The current wordpress-activitypub plugin has successfully contributed to connecting WordPress blogs with the Fediverse. However, it originated as a project led by a single developer and is now undergoing a significant transition into a dedicated team effort under Automattic.¹ This development raises the demand for scalability, feature expansion, and stability improvements, yet the existing architecture shows limitations in efficiently accommodating these new requirements.

Although this report cannot access the specific discussions within GitHub Issue #2073², it proposes a comprehensive redesign strategy based on a broad analysis of the plugin’s ecosystem and user experience. The proposal emphasizes resolving problems such as tightly coupled structures, limited extensibility, and recurring debugging/reliability issues reported by users.³

The recommended direction applies modern PHP design principles—such as Dependency Injection (DI) and the SOLID principles—to create a modular, service-oriented design.

Key recommendations include:

• Decoupling core ActivityPub protocol logic from the WordPress application layer
• Introducing a robust FederationEngine service for handling all S2S (server-to-server) and C2S (client-to-server) communications
• Implementing a DataPersistence abstraction layer for storage independent of WordPress’s database
• Establishing clear API contracts to formalize extensibility for future features

---

1. Analysis of Current Architecture and Problems

1.1 Functional Overview and Observed Behavior

The wordpress-activitypub plugin successfully transforms blogs into federated profiles within the Fediverse by generating accounts for both the site as a whole and its individual authors. For instance, if the website is example.com, the plugin generates both a site-wide profile ([email protected]) and per-author profiles like [email protected].⁵

The primary feature is a publish–subscribe model, allowing followers to receive updates in their home feed whenever a new post is published.⁶ The plugin demonstrates compatibility with a wide range of Fediverse platforms, including Mastodon, Pleroma, and Misskey.⁵

It supports outbound Create, Update, Delete activities and inbound Create (post), Update (post/comment), Follow, Undo (unfollow), Delete activities.⁷

However, early user experience reveals instability. Users frequently report missing posts and unsynchronized follower lists, suggesting deeper communication and data layer issues.³ Moreover, since native following from within WordPress was highly complex, the earlier versions heavily relied on other plugins like Friends or Enable Mastodon Apps to fill in missing functionality.¹

1.2 Identified Architectural Defects

• Monolithic and tightly coupled design: Current structure likely mixes WordPress-specific logic with ActivityPub protocol logic, violating the Single Responsibility Principle (SRP).⁸ This results in rigidity and poor maintainability.
• Poorly exposed APIs: Documentation such as developer-docs.md reveals limited extensibility—detailing only a single filter (activitypub_admin_settings_tabs)—showing that the core protocol, remote fetching, and profile management logic are not adequately exposed for developers.⁹ This forces third-party developers to "patch together" functionality, creating fragmented and unstable user experiences.¹
• Weak protocol handling and data synchronization: Reports of HTTP 403 errors, broken signed requests, and "outdated forum" experiences highlight vulnerabilities in state management.⁴ Inefficient implementation of ActivityPub can even trigger unintended DDoS-like behavior when multiple instances attempt simultaneous previews.¹⁰
• Poor testability and maintainability: Mixed concerns (external API handling embedded in WordPress logic) make automated unit testing nearly impossible—problematic now that Automattic is backing the project.¹

Table 1 and subsequent sections (omitted here for brevity in overview) compare current vs proposed functionality at a detailed level.

---

2. Principles for the New Architecture

2.1 Service-Oriented Approach

The redesign shifts from a monolithic to a Service-Oriented Architecture (SOA).¹¹ Each service handles a single, well-defined responsibility, ensuring modularity and SRP compliance.⁸

2.2 Adoption of Modern PHP Design Patterns

• Dependency Injection (DI): Dependencies are injected externally rather than instantiated inside classes, increasing flexibility, testability, and maintainability.¹⁴
• SOLID Principles:
  • SRP: FederationEngine handles communication; DataPersistence manages storage; PostMapper converts WordPress posts to ActivityStreams objects.
  • OCP: Extensible by adding new implementations without modifying core.¹³
  • ISP: Favor small, concrete interfaces like FollowerStoreInterface or InboxHandlerInterface.

2.3 Decoupling from WordPress Core

Core ActivityPub logic becomes an independent, vendor-neutral PHP library. The WordPress plugin layer acts as a thin wrapper, mapping WordPress actions (e.g., save_post, comment_post) to library calls. This separation enhances portability, testing, and reuse.

---

3. Proposed Component-Based Architecture

• FederationEngine Service: Dedicated to S2S and C2S interactions, HTTP signatures, and validation. Inspired by ActivityPhp, with configurable retries, timeouts, and authentication handling.¹⁷
• DataPersistence Layer: Abstract repositories (e.g., RepositoryInterface) for actors, followers, and activities. Default implementation uses WordPress DB, but Redis or future backends are possible.
• Core Logic Services (ActivityService & ActorService): Manage activity lifecycle and actor (profile) resolution. Inject dependencies via constructors for clarity and testability.
• WordPress Integration Layer: Minimal glue code that links hooks, REST endpoints, and admin UIs with the core services.

---

4. Solving Core Problems

• Eliminates the “patchwork” problem by establishing a public, stable API surface for addons. Future sub-plugins (e.g., microblogging, events) integrate cleanly via WordPress 6.5 plugin dependencies.¹⁹
• Improves performance and resilience via centralized, well-tested federation communication logic, reducing vulnerability to accidental DDoS amplification.
• Enhances developer and user experience with consistent logging, detailed error messages, and more transparent mental models of how services interact.

---

5. Implementation & Migration Strategy

• Phase 1: Build vendor-neutral core services (FederationEngine, DataPersistence interfaces, ActivityService, ActorService). Provide a simple DI container.
• Phase 2: Implement WordPress integration layer. Refactor hooks and REST endpoints to rely on the new services.
• Phase 3: Release as beta (behind feature flag), gradually replace old tightly coupled code, and document fully as a stable API.

---

Conclusion

The wordpress-activitypub plugin is a vital gateway to the Fediverse. Its transition into Automattic’s stewardship is of strategic importance. The proposed redesign—shifting from a monolithic structure to a modular, service-oriented architecture guided by Dependency Injection and SOLID principles—lays a foundation for stability, extensibility, and maintainability.

This transformation addresses current pain points (performance, debugging difficulty, external dependency patchwork) while elevating the plugin from a product into a true platform, enabling a strong and collaborative ecosystem for future development.

---