Technical Manual

Technical reference for extending the control plane and storefront safely with human+AI collaboration.

English Svenska Español

Audience: Developers and AI-agent operators

Back to docs

Core architecture terms

Bridge plugin: WordPress extension that performs onboarding, heartbeats, and capability reporting.

Control plane: RAGBAZ.xyz worker that stores snapshots/history and serves docs, peer, and tenant pages.

Storefront: public-facing worker that consumes WordPress GraphQL with hardening and fallback behavior.

Key endpoints and flows

/api/v1/home GET issues challenge. /api/v1/home POST registers site. /api/v1/home/heartbeat POST updates runtime state.

Tenant claim and slug claim endpoints bind a site to a stable public identity.

Safe extension workflow

Land changes in small slices, keep docs and coop log updated, and avoid broad unreviewed refactors.

When adding UI features, define fallback states and non-200 observability first.

Cache matrix and refresh rules

GraphQL edge cache: 60s + 120s stale (defaults via GRAPHQL_EDGE_CACHE_TTL_SECONDS and GRAPHQL_EDGE_CACHE_STALE_SECONDS).

Menu caches: snapshot 5m, URI existence 5m, sitemap 10m (MENU_SNAPSHOT_TTL_MS, MENU_URI_CHECK_TTL_MS, MENU_SITEMAP_TTL_MS).

Probe cache: STOREFRONT_GRAPHQL_PROBE_TTL_MS defaults to 900000ms (15m). Shop route ISR defaults to revalidate 300s.

Use /api/admin/purge-cache and a WordPress object-cache flush after route/menu/schema updates.

Observability now in response headers

Server-Timing includes app_ms, wp_ms, and menu_ms for dynamic responses.

Use these values together with web vitals and non-200 logs to separate upstream latency from app-path latency.

Prefer typed payload normalization at boundaries.
Treat docs as a user feature, not afterthought.
Keep admin/operator labels explicit and low ambiguity.
Document default cache durations when changing caching code.

Mermaid diagram

sequenceDiagram participant WP as WordPress + Bridge participant CP as RAGBAZ.xyz control plane participant SF as Storefront worker WP->>CP: GET /api/v1/home (challenge) WP->>CP: POST /api/v1/home (register signed payload) WP->>CP: POST /api/v1/home/heartbeat SF->>CP: Read tenant metadata / diagnostics CP-->>SF: Control-plane context