# WB Listora — Long-Term Stability Plan > Internal document. Read this before you write a line of code. > Last updated: 2026-04-21 --- ## 1. North Star In 18 months, WB Listora is the directory plugin that site owners reach for when they want a genuinely fast, block-based experience — and that app developers reach for when they need a clean, predictable REST API on day one. Every competing plugin in this space still routes user actions through `admin-ajax.php` and renders pages with jQuery. We do not. That technical gap is our moat. We defend it by keeping every architectural pillar non-negotiable, by shipping the reference app that proves our API works, and by being the only directory plugin with meaningful CI gates that would actually catch a regression before it ships. --- ## 2. Competitive Positioning | | Directorist | GeoDirectory | HivePress | Business Dir. Plugin | **WB Listora** | |---|---|---|---|---|---| | **JS stack** | jQuery | jQuery + some Vue | Vanilla JS / React (HivePress 2.x) | jQuery | Interactivity API (zero jQuery on frontend) | | **Admin API** | admin-ajax | admin-ajax | mixed | admin-ajax | REST (39 Free + 21 Pro endpoints); settings save still form-POST — tracked as debt | | **Rendering** | Classic PHP | Classic PHP | Classic PHP templates | Classic PHP | Block-first, server-rendered with progressive hydration | | **App-ready** | None | Partial (WP REST core only) | Partial | None | Full (consistent envelope, WP_Error permission callbacks, app-password auth) | | **Theme override** | Locked (custom templates) | Partial | Partial | Locked | WooCommerce-style override at `{theme}/wb-listora/` | | **Free/Pro split** | Addons marketplace | Addons | Marketplace | Addons | Native (Pro as single add-on requiring Free) | **Honest notes:** - The "Admin API" row is where we are not yet ahead of ourselves. Settings save still uses a form POST. That is the most important debt item this quarter. - HivePress 2.x is moving to React. We are not. That is a deliberate bet: IA gives us SSR + progressive hydration without a client-side bundle. If that bet is wrong, we revisit in Phase 2. - GeoDirectory has more addon volume and a larger ecosystem. We do not compete on addon count — we compete on core quality. --- ## 3. Architectural Pillars ### Pillar 1: 100% REST-ready **What it means.** Every user-facing action — submit a listing, toggle a favorite, vote on a review, save a search, purchase a credit pack — must be reachable over `listora/v1` with application-password authentication. The admin dashboard must use the same endpoints an external app would use. Two exceptions are permitted and must be documented: the webhook receiver (`class-webhook-receiver.php`) which receives inbound POSTs from payment processors, and any WordPress core lifecycle hook (activation, deactivation) that has no REST analog. **How we verify it.** The `wb-listora-app-starter` reference app (Phase 1 deliverable) must complete a full user journey — register, submit listing, favorite, review, dashboard view — using only `listora/v1` endpoints over application passwords, with zero `admin-ajax.php` calls in the network log. **What we give up.** We cannot use `wp_ajax_*` hooks for any new feature. This adds a few hours to each feature ticket because you must also write the REST route. We accept that cost. --- ### Pillar 2: Block-based + Interactivity API **What it means.** All 11 blocks use `apiVersion: 3`, register a `viewScriptModule` (ESM, not classic IIFE), and import the shared IA store from `src/interactivity/store.js`. No block has inline `onclick`, `alert`, or `confirm`. All actions live in the single `listora/directory` namespace in the shared store. No block loads jQuery. No block loads a third-party JS framework (React, Vue, Alpine). **How we verify it.** The CI WPCS check catches `onclick` in PHP. The ESLint config (once added — see debt) catches event binding outside the store. Any PR that adds a second IA namespace or a new `import { useState }` must be rejected at review. The `Listora_Block_Base` PHP class (Phase 1) will enforce that every block has `viewScriptModule` set; a missing entry throws an exception in `WP_DEBUG` mode. **What we give up.** No React-based block editor components beyond what `@wordpress/components` provides. No SPA routing between listing detail pages. No third-party map SDK that requires its own JS bundle (Google Maps JS is loaded only when the Pro Maps feature is active; the Free map uses Leaflet loaded as a module). These constraints keep our frontend JS bundle well under the 150 KB uncompressed target. --- ### Pillar 3: Fast rendering **What it means.** Blocks render meaningful HTML on the server. The client hydrates progressively — the listing grid is readable before JS loads. Database queries inside `render.php` are bounded: one `Listing_Data::load()` call per card, not one `Meta_Handler::get_all_values()` call per field. Meta and term caches are primed with `update_postmeta_cache()` / `update_object_term_cache()` before any `prepare_*` loop. REST list endpoints return at most 20 items by default (hard-capped at 100). Dashboard stats are cached in a 60-second transient. **How we verify it.** Phase 1 adds a `.size-limit.json` file and a Lighthouse CI action. Lighthouse score must be >= 90 on the reference listing grid page. Bundle size CI fails if any individual block's viewScriptModule exceeds the budget. These checks run on every PR targeting `main`. **What we give up.** We cannot add a real-time WebSocket feature, a client-side search-as-you-type that hits every keystroke, or any feature that requires loading a second JS runtime. Push notifications are delivered via outgoing webhooks (Phase 2), not a persistent socket. --- ## 4. Current State Snapshot ### Solid - REST envelope consistency (`items`, `total`, `pages`, `has_more`) across all 60 endpoints. - All permission callbacks return `WP_Error`, never bare `false` — apps get HTTP status codes they can act on. - CI gates: PHP Lint, WPCS, PHPStan L7, PHPUnit, PCP (noise-filtered) — all green on Free and Pro. - 11 blocks on IA with shared store and single namespace. No jQuery in any `view.js`. - Four documentation tiers: `REST-API.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, `docs/website/` customer docs. - Template override system documented and functional for `listing-card`, `listing-detail`, `user-dashboard`. - `Listing_Data` helper class separates DB queries from `render.php`. - Write-operation hooks (`before_` / `after_`) on every CRUD operation — Pro and extensions can intercept without forking. ### Shaky - **Admin still has form-POST paths.** Settings save (`class-settings-page.php`), claims moderation, and reviews moderation do not go through the REST API. A React Native app cannot perform admin operations. - **No performance budget enforcement in CI.** We know we're fast; we cannot prove it won't regress on the next PR. - **No Lighthouse benchmark on record.** We have not run a baseline score. We do not know our current number. - **No sample app.** The "REST-ready" claim is architectural, not demonstrated. No reference app exists that would catch a broken endpoint before a customer reports it. - **CAPTCHA bypass landed this week.** reCAPTCHA v3 + Turnstile are new. The rate-limiting logic is untested under load. Monitor for false positives on mobile IPs. - **Saved-search PUT landed this week.** Edge case: a user with a saved search whose criteria include a listing type that is later deleted. Not yet handled. ### Missing - `Listora_Block_Base` PHP class — blocks are consistent but not enforced by a common parent. - REST base controller class — each controller reimplements envelope assembly. Not yet extracted. - Block pattern library — no drop-in compositions exist. - Type-aware template variants — restaurant and hotel render the same card layout. - `.size-limit.json` and Lighthouse CI action. - `.github/pull_request_template.md`. - ESLint config for IA store discipline. - GraphQL layer. - Service worker / PWA manifest. --- ## 5. 18-Month Roadmap ### Phase 1 (0–6 months): Make the claims defensible This phase is about closing the gap between what we say and what we can prove. Every item here either prevents a regression or enables the reference app. **Infrastructure** - `Listora_Block_Base` PHP abstract class. Every block's `render_callback` must extend it. Enforces: `viewScriptModule` present, `Block_CSS::render()` called, template override path checked. Missing any of these throws a `_doing_it_wrong()` in `WP_DEBUG` mode. - REST base controller class `Listora_REST_Controller`. Extracted from `class-listings-controller.php`. Provides: `envelope()`, `require_logged_in()`, standard `register_routes()` stub. All 10 Free controllers refactored to extend it. - `.size-limit.json` — per-block JS budget, total CSS budget. Fails CI if exceeded. - Lighthouse CI GitHub Action — runs against staging URL on PRs. Required score >= 90. Blocks merge if it fails. - ESLint rule: no IA actions outside `store.js`, no second IA namespace registration. **Admin dogfooding REST** - Refactor settings save to POST to `listora/v1/settings` (endpoint exists in `class-settings-controller.php`; admin form currently bypasses it). - Refactor claims moderation and reviews moderation admin pages to use `listora/v1/claims` and `listora/v1/reviews` — same endpoints the frontend blocks use. - Inline `