Skip to content

Architecture

Jump to bottom
Nick edited this page Mar 8, 2026 · 2 revisions

Architecture

This page describes how Dispatch is structured internally — useful for contributors, reviewers, or anyone integrating with the plugin.

Layered Design

Dispatch follows a strict five-layer architecture. Each layer has a single responsibility and communicates only with the layer directly below it.

┌─────────────────────────────────────────┐
│         React UI  (src/)                │  Admin & Device Flow apps
├─────────────────────────────────────────┤
│         REST API  (Telex_REST)          │  telex/v1 endpoints
├─────────────────────────────────────────┤
│         Services  (includes/)           │  Auth, Installer, Updater,
│                                         │  Tracker, Cache, Circuit Breaker
├─────────────────────────────────────────┤
│         Telex SDK  (lib/telex-sdk/)     │  PSR-18 HTTP abstraction
├─────────────────────────────────────────┤
│         WP HTTP Client                  │  Bridges PSR-18 → wp_remote_*
└─────────────────────────────────────────┘

The React UI only talks to the REST layer — never directly to PHP service classes. Service classes never make HTTP requests directly — always through the SDK and Telex_WP_Http_Client.

Key Classes

Class File Responsibility
Telex_Admin includes/class-telex-admin.php Admin menu, asset enqueuing, Site Health, Heartbeat
Telex_REST includes/class-telex-rest.php REST routes under telex/v1
Telex_Auth includes/class-telex-auth.php AES-256-GCM token encryption, device flow state
Telex_Installer includes/class-telex-installer.php Download, validate, and install project builds
Telex_Updater includes/class-telex-updater.php Inject Telex projects into the WP Updates screen
Telex_Tracker includes/class-telex-tracker.php wp_options-backed registry of installed projects
Telex_Cache includes/class-telex-cache.php Transient cache with stale-while-revalidate
Telex_Circuit_Breaker includes/class-telex-circuit-breaker.php Three-state circuit breaker for API resilience
Telex_Audit_Log includes/class-telex-audit-log.php Custom DB table for security and activity events
Telex_Notifications includes/class-telex-notifications.php Email and Slack webhook dispatch
Telex_Analytics includes/class-telex-analytics.php Block usage counting from post_content
Telex_Snapshot includes/class-telex-snapshot.php Build snapshot create/restore logic
Telex_WP_Http_Client includes/class-telex-wp-http-client.php PSR-18 adapter over wp_remote_*
TelexClient lib/telex-sdk/src/TelexClient.php SDK entry point

Value Objects (DTOs)

Three immutable value objects cross layer boundaries:

Class Description
Telex_Project A project from the Telex API (id, name, type, latest build)
Telex_Build_File A file within a build (path, SHA-256 checksum)
Telex_Api_Credentials API base URL + bearer token pair

REST API Endpoints

All endpoints are under the telex/v1 namespace and require manage_options unless noted.

Method Path Description
GET /projects List all Telex projects (cached)
POST /projects/<id>/install Install a project by ID
DELETE /projects/<id> Remove an installed project
POST /auth/device Start device authorization flow
GET /auth/device Poll for authorization completion
DELETE /auth/device Cancel an in-progress device flow
DELETE /auth Disconnect (remove stored token)
GET /auth/status Current connection and circuit breaker status
GET /installed List locally installed projects
POST /deploy Auto-deploy trigger (no capability required, HMAC-validated)
POST /circuit/reset Reset circuit breaker to closed state

OAuth 2.0 Device Authorization Flow

WordPress Admin          Dispatch REST API         Telex Cloud
      │                        │                        │
      │  POST /auth/device     │                        │
      │───────────────────────>│  Request device code   │
      │                        │───────────────────────>│
      │                        │<── { device_code,      │
      │<── { user_code, url } ─│      user_code, url }  │
      │                        │                        │
      │  (user opens URL,      │                        │
      │   enters code)         │    User authorizes     │
      │                        │                        │
      │  WP Heartbeat poll ───>│  Poll for token ──────>│
      │                        │<── { access_token }    │
      │<── { authorized: true }│                        │

Device flow state is stored in a short-lived WordPress transient. Polling uses the WordPress Heartbeat API supplemented by an RFC 8628-compliant interval timer in the React client.

Data Flow: Install a Project

React UI
  └─ POST telex/v1/projects { id }
       └─ Telex_REST::install_project()
            ├─ Telex_Auth::get_client()           → SDK credentials
            ├─ TelexClient->projects->getBuild()  → build manifest
            └─ Telex_Installer::install()
                 ├─ Download files (Telex_WP_Http_Client)
                 ├─ Validate SHA-256 checksums
                 ├─ Validate paths (ZipSlip, extension blocklist)
                 ├─ WP_Upgrader::install()
                 ├─ Telex_Tracker::track()        → record in wp_options
                 └─ Telex_Audit_Log::log()        → write audit event

Build System

Entry point Output When loaded
src/admin/index.js build/admin.js Connected admin screen
src/device-flow/index.js build/device-flow.js Disconnected connect screen
src/admin/commands.js build/commands.js WP-CLI JS side

The build/ directory is not committed. Run make build to generate it.

Project Structure

dispatch/
├── includes/          PHP classes
├── src/
│   ├── admin/         React admin screen (index.js + store.js)
│   └── device-flow/   OAuth device authorization flow UI
├── lib/telex-sdk/     Embedded PHP SDK (PSR-18)
├── tests/             PHPUnit + Jest test suites
├── bin/               Build and setup scripts
└── assets/css/        Compiled CSS

WordPress Integration Points

Hook Purpose
pre_set_site_transient_update_plugins Inject Telex updates into WP Updates screen
plugins_api Provide plugin info for the WP update modal
upgrader_process_complete Post-install tracking and audit logging
rest_api_init Register telex/v1 routes
admin_menu Register the Dispatch admin page
heartbeat_received Handle device flow polling
site_health_info Surface connection status in Site Health
wp_privacy_personal_data_exporters GDPR audit log export
wp_privacy_personal_data_erasers GDPR audit log erasure

Clone this wiki locally