Architecture overview

Architecture overview

HeadlessWP Pro separates the customer-facing app from the WordPress origin with a strict boundary model. This keeps the UI fast and predictable while reducing exposure to backend changes.

Boundary model at a glance (text diagram)

Browser (headlesswppro.io)
  -> Next.js app routes
    -> /api/secure/** proxy boundary (deny by default)
      -> WordPress origin (secure.headlesswppro.io)
        -> /wp-json/headlesswp/v1/* and allowlisted plugin endpoints

What this means in practice:

• The browser calls the site origin only.
• The secure WordPress origin is not called directly from client-side code.
• All upstream calls pass through the secure proxy, where policy is enforced centrally.

Plugin endpoints and the secure proxy boundary

The upstream API surface is versioned and plugin-owned. The app consumes only explicit, allowlisted endpoints.

• HeadlessWP Pro endpoints are namespaced under /wp-json/headlesswp/v1.
• Protected Files Pro endpoints are available only when explicitly allowlisted.
• The proxy is deny-by-default, so routes, methods, and query keys must be intentionally approved.

This boundary helps prevent accidental API sprawl and gives teams one place to enforce request rules.

Versioned namespaces and response envelopes

HeadlessWP Pro uses versioned namespaces (for example, v1) to keep integrations stable over time.

Responses are designed around a consistent envelope pattern so clients can reliably parse success and failure cases. This improves:

• typing and contract testing,
• safer rollout of additive changes,
• faster support diagnostics.

Capability detection flow

The app performs capability detection before enabling portal behavior that depends on plugin features.

Typical flow:

1. Load baseline app state through approved public reads.
2. Check capability and/or entitlement endpoints through /api/secure/**.
3. Enable or hide UI actions based on the returned capabilities.
4. Keep unsupported features gated instead of guessing fallback behavior.

This avoids broken UX when environments differ by plugin version or extension configuration.

Why deny-by-default matters

Deny-by-default is important because it converts unknown behavior into explicit policy decisions.

Benefits include:

• Safer change management: new routes do not become reachable by accident.
• Tighter request controls: unexpected methods and query keys are blocked.
• Clear auditability: route access is documented and tested as a contract.
• Lower incident blast radius: misconfigurations fail closed instead of open.

For customers, this translates to predictable integrations, easier compliance reviews, and faster incident response.