Documentation

Implementation and operational reference — pipeline integration, API surface, operational tooling, cache configuration, and debugging workflows.

Getting started

FlxWoo has two components: the Core plugin and the Render service. Both must be configured before pipeline routing is activated.

1
Install Core
Install the FlxWoo Core plugin into your WooCommerce environment. Core registers the execution pipeline — field registry, resolution, validation, and Control. It does not activate pipeline routing until step 3.
2
Deploy the Render service
Deploy the FlxWoo Render service. The Render service operates independently from WooCommerce — it does not require WordPress or database access. Configure the render endpoint in Core settings so execution snapshots are delivered to the correct address.
3
Enable pipeline routing
Activate FlxWoo pipeline routing. Checkout requests will pass through the five-phase sequence: Registration → Resolution → Validation → Render → Output. WooCommerce native rendering remains available as fallback.
4
Verify pipeline execution
Run a checkout request and inspect the pipeline trace. Confirm all five phases executed, review field registration, resolved values, and render output.
5
Verify cache configuration
Run the cache verification tool to confirm checkout, cart, and API endpoints are excluded from page cache and CDN edge cache. See cache configuration below before routing production traffic.
6
Run smoke tests
Execute the pipeline integrity smoke tests. These verify field registration, validation, and render phases against a known-good input set and confirm both Core and the Render service are operating correctly together.

Core concepts

These terms are defined in full in the architecture specification.

Field
A single checkout data element with a key, type, provider, and priority.
Registry
The canonical collection of all fields. Closed after registration completes — no additions downstream.
Resolution
Priority-based value assignment from ordered sources. Not hook-order-dependent.
Validation
Per-field and cross-field rule evaluation against resolved state. Produces structured failure data. Does not mutate values.
Render service
A dedicated service and pure consumer of validated field state. Produces product, cart, checkout, and thank-you page output. No write path back to Core. Operates independently from WooCommerce rendering.
Pipeline
The full five-phase execution sequence from field registration through output delivery. Fixed order, sequential.
Phase
One discrete step in the pipeline. Must complete before the next begins.

Render service

The FlxWoo Render service is a separate component from Core. It receives immutable snapshots from Core and produces page output. It does not require WordPress or WooCommerce database access.

Render endpoint configuration

The render endpoint is configured in Core settings. Core delivers execution snapshots to this endpoint after the Validation phase completes. The Render service must be reachable from the WooCommerce server. If the endpoint is unreachable, times out, or returns an error, Core falls back to WooCommerce native rendering and logs the degradation event.

Supported view types

Product — product display
Cart — cart state
Checkout — checkout form with validation state
Thank-you — order confirmation

Snapshot delivery

Core delivers an immutable snapshot of validated field state to the Render service. The snapshot contains field definitions, resolved values, and validation results. Render cannot modify the snapshot or request additional state from Core mid-render.

Fallback behavior

If the Render service is unavailable or returns an error, Core falls back to WooCommerce native rendering. The fallback event is logged with the failure reason. Configure the render timeout in Core settings to control how long Core waits before triggering fallback.

Integration flow

Integrating with FlxWoo means registering fields into the pipeline and consuming rendered output.

1
Define field providers
A field provider declares which fields it contributes and at what priority. Priority determines resolution order when multiple providers register the same field key.
2
Register fields into Core
Fields are submitted to the registry during the Registration phase. After registration closes, the registry is immutable.
3
Execute pipeline
Control runs the five-phase pipeline. Registered fields are resolved, validated, and rendered in sequence.
4
Receive rendered output with trace
The pipeline returns final checkout output plus a structured trace. Use the trace for verification, debugging, and operational auditing.

Execution example

Field registration, pipeline execution, and trace inspection.

// Register fields during Registration phase
registerField({
  key: "billing_email",
  type: "email",
  required: true,
  priority: 10,
})

registerField({
  key: "billing_phone",
  type: "tel",
  required: false,
  priority: 20,
})

// Execute the full five-phase pipeline
const result = runPipeline()

// result.trace — structured execution log
// {
//   requestId: "flx_req_01J...",
//   phases: {
//     registration: { status: "complete", fieldCount: 2, duration: 4 },
//     resolution:   { status: "complete", resolved: 2, null: 0 },
//     validation:   { status: "complete", failures: [] },
//     render:       { status: "complete", duration: 12 },
//     output:       { status: "complete" },
//   },
// }

// result.output  — rendered checkout HTML
// result.errors  — structured validation failures, if any
// [{ field: "billing_email", rule: "required", message: "Required" }]

Configuration

Field priority
Each field has a numeric priority. When multiple providers register the same key, the highest-priority provider wins. Priority determines resolution order, not registration order.
Validation rules
Rules are attached per-field or as cross-field constraints. Built-in rules cover type checking, required fields, and format validation. Custom rules register alongside fields.
Render overrides
Default render behavior can be overridden per field or per field group. Overrides receive the same validated state as the default renderer — they cannot bypass validation.

Operational tooling

FlxWoo checkout failures are reproducible and traceable. The execution pipeline produces structured artifacts at every execution — regardless of success or failure. This tooling is designed around the assumption that production incidents should be diagnosable from logs and traces, not from live reproduction.

Smoke tests
Pipeline integrity checks executed post-deployment. Verify that all five phases complete against a minimal known-good input set. Failures surface phase-level detail.
Replay tooling
Re-execute a past pipeline execution from its trace log. Accepts a request ID and replays the execution with the same field input state, producing a new trace for comparison.
Deployment verification
Scripts that confirm pipeline availability, subsystem registration, and configuration correctness after environment changes or deployments.
Request tracing
Each pipeline execution produces a trace record keyed by request ID. Retrieve and inspect traces with getPipelineTrace(requestId).
Webhook replay
Re-execute a webhook event from its stored payload. Used to reproduce and debug webhook handling behavior without triggering an external event.
Log integrity auditing
Observability scripts validate that execution logs are complete, sequential, and free from gap patterns that indicate pipeline interruption or logging failures.
Idempotency tooling
Inspect and manage idempotency keys for payment and order operations. Identifies duplicate submissions and their resolution outcomes.
WP-CLI diagnostics
Command-line tools for inspecting registry state, running pipeline checks, querying execution logs, and managing operational configuration from the server environment.

Cache configuration

Incorrect cache configuration is one of the most common causes of inconsistent checkout behavior.

Checkout execution is stateful and deterministic. A cached checkout response reflects a previous request's resolved field state, session context, and validation output — not the current request's. Serving cached checkout responses corrupts execution determinism.

Cloudflare configuration

Add a Cache Rule bypassing cache for checkout, cart, account, and API endpoints. Set cache status to BYPASS for all paths matching WooCommerce session-bearing routes. Verify with the CF-Cache-Status response header.

Page cache exclusions

The following paths must be excluded from page caching at the server or plugin level:

/checkout/
/cart/
/my-account/
/wp-json/wc/
Any URL with wc-ajax query parameter

WooCommerce session handling

Requests bearing WooCommerce session cookies (woocommerce_session_*, woocommerce_cart_hash) must not be served from cache. Configure cache rules to bypass on cookie presence, not just on path.

API no-cache requirements

All WooCommerce REST API endpoints and AJAX endpoints must return Cache-Control: no-store, no-cache. These endpoints carry session state and pipeline results. Caching them produces stale checkout state.

CDN edge behavior

Authenticated requests must bypass CDN edge caches. Verify that your CDN is not normalizing or stripping cookies before cache key evaluation. Edge caches that do not vary on session cookies will serve incorrect checkout state to different users.

Verification

Use the FlxWoo cache verification tool to confirm exclusions are applied correctly. The tool checks response headers for checkout, cart, and API endpoints against expected no-cache behavior and reports any endpoints returning cached responses.

Debugging

FlxWoo checkout failures are reproducible and traceable. The pipeline produces structured artifacts at every execution.

Request IDs
Every pipeline execution generates a unique request ID. Use the ID to retrieve the full trace, replay the execution, or correlate logs across phases.
Execution traces
The trace contains the complete record of a single pipeline execution: fields registered, values resolved (with source decisions), validation results, and render output. Every trace is produced regardless of success or failure.
Phase logs
Each phase logs start, completion, and any errors. If a pipeline halts, phase logs show exactly where execution stopped and why.
Structured validation failures
Failures are typed records: field key, rule name, message. They appear in the trace and are passed to Render as field metadata. Inspect to determine why a field is in an error state.
Replay debugging
Reproduce a past failure by replaying its execution from the trace log. The replay produces a new trace under current pipeline state, allowing comparison against the original failure.
Deterministic reproduction workflow
Retrieve the request ID from the failed checkout. Run getPipelineTrace(requestId) to inspect the execution. Use replay tooling to reproduce under controlled conditions. Compare traces to isolate the phase and field where behavior diverges.

API overview

The API surface is organized by subsystem. Each function operates within its subsystem's boundary.

Core

registerField — add a field to the registry
resolveField — resolve a field's value from sources
validateField — run validation rules against a field
getRegistry — inspect the current registry

Render

renderField — produce output for a single field
renderFieldGroup — produce output for a field group
setRenderOverride — override default render for a field

Control

runPipeline — execute the full five-phase pipeline
getPipelineTrace — retrieve execution trace by request ID
getPhaseStatus — check completion status of a phase

Operational

runSmokeTest — execute pipeline integrity tests
replayExecution — replay a past execution from trace
verifyCacheConfig — check endpoint cache exclusions
auditLogIntegrity — validate execution log completeness