Architecture

Architecture

Dashless is a local-first publishing pipeline. WordPress stores the editorial truth; Astro compiles that truth into static output; a small WordPress companion supplies the site contract and WP Cloud routing.

Components

Local Codex plugin

The MCP server under server/ uses Node.js built-ins. It:

• connects to WordPress with a dedicated Application Password;
• inspects and edits core WordPress content through REST;
• keeps idempotency keys, staged changes, and preview locks outside the Astro repository;
• creates and builds the owned Astro project;
• compares WordPress content generations before and after builds;
• deploys through a local filesystem, SSH/rsync, or key-based SFTP; and
• verifies the public WP Cloud release.

It is invoked by the skills packaged under skills/. There is no remote Dashless coordinator.

WordPress companion

wordpress/dashless-wpcloud.php can run as a conventional plugin or a must-use plugin. It:

• exposes the authenticated /wp-json/dashless/v1/site contract;
• increments a monotonic content generation when Posts, Pages, terms, or attachments change;
• exposes authenticated release status, activation, and rollback routes;
• verifies every WP Cloud release file against its SHA-256 manifest before activation;
• keeps WordPress system routes available while serving the static reader site; and
• supplies optional privacy-minded reader interaction endpoints.

Astro project

templates/astro/ becomes a new user-owned project. At build time it reads published WordPress data, mirrors media into the static tree, creates routes and social cards, and emits dist/. Preview builds may overlay one authorized draft or staged change without modifying the source of truth.

At request time, Astro is not running. Readers receive prebuilt files.

Content flow

sequenceDiagram
    participant U as User
    participant C as Local Codex + Dashless
    participant W as WordPress
    participant A as Astro build
    participant H as Public host

    U->>C: Request editorial change
    C->>W: Read current item + modified_gmt
    C->>W: Save draft or keep published change staged
    C->>A: Build exact preview
    A->>W: Read canonical published content
    A-->>C: Static site + content digest
    C-->>U: Local preview
    U->>C: Explicit approval
    C->>W: Publish only matching payload
    C->>A: Build at stable content generation
    C->>H: Upload immutable release
    C->>H: Activate and verify

Loading

Content generations

The companion stores a monotonic generation number. A relevant WordPress change increments it. get_status compares the current generation with the last locally built and deployed generations.

Preview and production builds read the generation before and after Astro runs. If it changed, the build is rejected. WP Cloud release manifests carry that generation, and the companion refuses activation when WordPress has moved ahead.

This catches changes anywhere in the publication, not only the post currently being edited.

Preview overlays

New drafts live in WordPress. Changes to already-published content and revision restorations remain local staged payloads until approval. A preview build supplies exactly one overlay to Astro, which renders it at the real route while the rest of the site comes from current published WordPress content.

The overlay is temporary and never becomes deployable fallback content.

WP Cloud request routing

WP Cloud exposes one public document root. Dashless places immutable releases under wp-content/uploads/dashless/releases/<id> and installs the companion under wp-content/mu-plugins/.

The companion reserves WordPress system paths and routes reader-facing requests to the selected release:

Request	Handler
/wp-admin, /wp-login.php	WordPress
/wp-json, ?rest_route=	WordPress REST
/wp-cron.php, feeds, system endpoints	WordPress
Existing release asset	Static file
Reader page such as /stories/example/	Active Astro index.html for that route
Missing reader route	Active Astro 404.html

The active release is one WordPress option. Activation changes that pointer only after complete upload and validation, making the switch atomic from the application perspective.

Trust boundaries

• WordPress owns production editorial content.
• The local Dashless process owns credentials and temporary editorial workflow state.
• The Astro repository owns presentation code, not canonical posts.
• The deployment host owns immutable static releases and the active pointer.
• Third-party discovery failures never fail publication.

See Publishing Safety for the exact state machine and Privacy and Security for credential handling.