RFC: Use WordPress as your app's data store #817

Idea

Headless Documents gives your app a database, using the WordPress site you already have. Turn on a small opt-in plugin, save JSON from your app, and never silently lose a write.

flowchart TD
  App["Your app"] -->|REST or GraphQL| WP["Plugin<br/>checks version"]
  WP --> T[("wp_headless_<br/>documents")]
  Admin["wp-admin<br/>Tools screen"] -.->|read-only| T

Why

• You don't need a second database like Firebase or Supabase, or a custom plugin.
• Normal WordPress and WPGraphQL saves let the last write win. Headless Documents rejects a stale write with a 409.
• Site owners can see the data in wp-admin, and WordPress users and roles control access.

Decided

• Documents live in one dedicated table, grouped into collections like Firestore. History can be added later without migrating data.

• REST and WPGraphQL can both get, update, delete, list and add documents, with the same version check.

• Collections are admin-only until you register them. Registering a collection sets its access mode and a JSON Schema that WordPress validates, which is how a form or waitlist accepts public writes:

  register_headless_collection( 'waitlist', array(
  	'access' => 'public-create', // or 'admin' (default) or 'owner'
  	'schema' => array( 'type' => 'object', 'required' => array( 'email' ) ),
  ) );

• A JS client for app servers would look roughly like this:

  const ref = store.collection('preferences').doc('user-42');
  await ref.update((d) => ({ ...d, theme: 'dark' })); // retries on conflict

Plan

1. Storage and REST, as a standalone plugin (prototyped in FaustWP in feat(faustwp): add an opt-in versioned document store with conflict detection faustjs#2674).
2. register_headless_collection with access modes and schemas.
3. WPGraphQL support.
4. The JS client.

Realtime, complex queries and high write volume are out of scope.