Skip to content

Architecture

Jump to bottom
Nick Hamze edited this page Sep 1, 2026 · 5 revisions

Architecture

The two roles

Fleet does not introduce a new WordPress site type.

  • The hub is the WordPress install where Fleet for OpenStation is activated alongside OpenStation.
  • A managed site is another WordPress install that approved that hub through WordPress Core's Application Password screen.

Fleet is installed only on the hub. OpenStation is installed or activated automatically on a managed site after approval. Each hub user's site list, agency metadata, activity, and encrypted credentials live in that user's metadata, so hub managers do not silently share connections.

Connection and installation

  1. The manager enters a public HTTPS WordPress URL.
  2. Fleet requests the site's REST index and discovers Core's Application Password authorization endpoint.
  3. Fleet creates a short-lived state value and a nonce-protected callback tied to the current hub user.
  4. The browser opens WordPress's native authorization screen on the managed site. WordPress asks the person to sign in there if necessary.
  5. Approval generates a separate, named Application Password and returns it directly to the hub callback.
  6. Fleet verifies the callback state, target origin, username, credential, and exact Application Password UUID.
  7. Fleet encrypts the credential and immediately opens a visible setup screen.
  8. That screen sends a nonce-protected request to the hub. Fleet uses the Core Plugins REST controller to install or activate the WordPress.org desktop-mode package.
  9. Fleet refreshes the site's advertised REST routes and Core Site Health results, then opens its managed-site workspace.

The installation request may take time while WordPress downloads the package. Fleet's progress screen keeps that work visible instead of leaving the browser on a blank callback. Reconnecting an already-known site opens its workspace and does not create a duplicate credential.

Remote requests

Fleet builds requests from the managed site's discovered REST root and authenticates with HTTP Basic authentication over HTTPS, using the approving username and the decrypted Application Password. The requested Core or plugin route still runs its normal permission_callback, capability checks, validation, and sanitization.

Focused views provide interfaces for content, comments, media, plugins, users, settings, and agency data. The Explorer reads the live REST index, lists every Core and plugin route with its supported methods and argument count, and accepts GET, POST, PUT, PATCH, and DELETE beneath the discovered REST root. Fleet cannot manage a feature that exposes no REST API.

Fleet-wide views

The hub's fleet-wide tools are composed from APIs WordPress already exposes:

  • Inbox reads pending comments, drafts, review-ready posts, and scheduled posts from Core collection routes, then combines them with the connection and Site Health information Fleet already keeps on the hub.
  • Search queries the managed site's Core search, posts, pages, media, comments, and users collections. A search is limited to the first 25 matching sites; selecting a client narrows larger fleets.
  • Client workspaces group the hub user's site records by their locally stored client name, then ask OpenStation to open each site in its own persistent window.

Inbox and Search use Core's /batch/v1 controller when the managed site advertises it. If the controller is unavailable, Fleet falls back to the same Core routes one at a time. The batch request changes the number of HTTP round trips, not the routes, permissions, or returned data.

Capability and health discovery

Fleet reads the REST index to decide which workspace tabs to show. It records route count, namespaces, Core coverage across content, taxonomies, navigation, widgets, templates, patterns, blocks, styles, fonts, administration, OpenStation plugin state, and supported Site Health endpoints.

A Core cron event refreshes connection and plugin status every 15 minutes. The heavier Site Health checks are refreshed at most every six hours unless the manager selects Check now.

Disconnecting

Fleet stores the exact UUID of the Application Password it created. Disconnect deletes that UUID through Core before removing the local site record. If the managed site is unreachable or refuses revocation, Fleet keeps the record so the manager can retry. An administrator can also revoke the named credential under Users → Profile → Application Passwords on the managed site.

WordPress and OpenStation building blocks

  • Core admin pages, forms, capabilities, nonces, AJAX, cron, user meta, and transients
  • Core safe HTTP functions, REST controllers, Site Health endpoints, and Plugins API
  • Core Application Password discovery, approval, introspection, and revocation
  • WordPress's bundled sodium compatibility layer for encrypted hub storage
  • OpenStation's window manager for a stable fleet-site-{id} window per managed site
  • The OpenStation os.window.geometry filter for centered, bounded Fleet and managed-site windows

Fleet Inbox, Search, and Workspaces add no target-site endpoint. They combine Core responses and hub-owned metadata inside the existing Fleet interface.

Fleet registers a standard wp-admin page. The hub opens normally, while each Manage action gives the selected site a stable OpenStation window identity. Reopening that site focuses its existing window; selecting another site opens another window. Workspace navigation is kept inside the owning iframe and the back action focuses the hub. Fleet therefore needs no OpenStation source change, separate application framework, target-site Fleet agent, hosted control plane, or custom database table.

Clone this wiki locally