FlxWoo architecture

System boundary

FlxWoo interposes between WooCommerce's hook system and the final checkout output. It governs the execution space between plugin field registration and rendered result. It does not replace WooCommerce internals.

FlxWoo reads from WooCommerce state. It does not write back to WooCommerce internals.

Execution lifecycle

Every checkout request executes the same five-phase pipeline. Phases are sequential. No phase begins until the previous phase completes. Control enforces this. Each phase has defined inputs, outputs, guarantees, and observability points.

1. 1

   Registration

   Input: WooCommerce checkout field filter chain and FlxWoo field providers.

   Output: Closed canonical registry. Duplicate keys resolved by provider priority.

   Guarantee: No new fields can be added after registration closes.

   Forbidden: Value resolution, validation, rendering, or output generation.

   Observability: Registry contents logged at phase close; provider failures logged with identity and error detail.

2. 2

   Resolution

   Input: Closed registry plus data sources: session, cart, user meta, plugin-provided defaults.

   Output: Field map with resolved values. Unresolvable fields receive null — no silent defaults.

   Guarantee: Resolution order is priority-based, not hook-order-dependent. Resolution is a pure function of inputs.

   Forbidden: Validation, rendering, or registry mutation.

   Observability: Resolved values and source decisions logged per field.

3. 3

   Validation

   Input: Resolved field state. Validation rules (per-field and cross-field).

   Output: Validated field state with structured failure data attached to each affected field.

   Guarantee: Validation never mutates field values. Failures are collected, not thrown. All rules run — evaluation is not short-circuited on first failure.

   Forbidden: Field mutation, registry modification, rendering, or output.

   Observability: Structured failure data logged as typed records: field key, rule name, message.

4. 4

   Render

   Input: Immutable snapshot of validated field state, including failure metadata for affected fields.

   Output: HTML fragments ordered by registry sort order, not render execution order.

   Guarantee: Render cannot call back into Core, trigger re-validation, add or remove fields, or access WooCommerce hooks directly.

   Forbidden: Any state mutation. Any write path back to Core.

   Observability: Render duration and field-level output logged. Render failures captured with full pipeline trace.

5. 5

   Output

   Input: Rendered HTML from the Render phase.

   Output: Checkout HTML delivered to WooCommerce output hooks plus a complete pipeline trace.

   Guarantee: Output failure falls back to WooCommerce default rendering. No partial output is delivered.

   Observability: Full trace — registry contents, resolved values, validation results, render output — emitted as a single structured log record per request.

Core

Core owns checkout state before rendering. Its output is a validated field state object. Everything downstream depends on this object.

Field registry

• Canonical list of all checkout fields
• Each field has a key, type, provider, and priority
• Fields are immutable after registration closes
• Registry is inspectable at any point via getRegistry

Data resolution

• Priority-based conflict resolution — not hook-order-dependent
• Null for unresolvable fields — no silent defaults
• Resolution is a pure function of inputs

Validation

• Per-field rules: type, required, format
• Cross-field rules: field A depends on field B
• Failures are structured data: field key, rule name, message
• Validation never modifies field values or the registry

Core does not

• Render HTML
• Bypass validation
• Deliver output
• Sequence phases

Render

Render is a pure consumer. It receives validated field state from Core and produces HTML. It has no write access to Core and no mechanism to trigger re-validation or modify field definitions.

Input contract

Render receives an immutable snapshot containing field definitions, resolved values, and validation results including failure metadata. Render cannot distinguish between a field that was never registered and a field removed before render — it sees only what Core provides.

Output

Render produces HTML fragments. Each fragment corresponds to one field or field group. Fragments are ordered by the registry's sort order, not by render execution order.

Render does not

• Mutate field state
• Access WooCommerce hooks directly
• Trigger re-validation
• Add or remove fields
• Query Core for additional data mid-render

Control

Control coordinates the pipeline. It does not define fields, resolve data, validate, or render. It sequences phases and enforces boundaries between them.

Phase sequencing

Control starts each phase, awaits completion, then starts the next. A phase that has not completed cannot be followed by another. The decision to halt or continue after a phase failure is per-phase, not global.

Error boundaries

Control wraps each phase in an error boundary. A validation failure does not prevent rendering — Render receives the failure metadata. A render failure halts the pipeline; no partial output is delivered. Control logs all phase transitions and failures.

Control does not

• Define fields
• Modify field values or validation rules
• Produce render output
• Carry data between subsystems

Data flow

Data flows in one direction. Core produces state. Render consumes state. No subsystem reads from a downstream subsystem. These constraints are structural, not conventional.

Control does not carry data. It enforces when each subsystem executes. Render cannot query Core for additional data mid-render. Core cannot inspect Render output.

Deterministic execution guarantees

These rules are always true during a FlxWoo pipeline execution. They are enforced by the system, not by convention.

1. 1

   Render never receives unvalidated field state. Validation must complete before Render executes.

2. 2

   Core never produces HTML output. Output generation belongs exclusively to Render.

3. 3

   Control never modifies field definitions, field values, or validation rules. It coordinates; it does not mutate.

4. 4

   No field can be added to the registry after registration closes. Late additions are rejected, not silently dropped.

5. 5

   Validation never mutates field values. It reads resolved state and produces failure data only.

6. 6

   Render has no write path back to Core. The data flow is unidirectional by design.

7. 7

   Phase N does not begin until phase N-1 completes. No phase can be skipped or run concurrently.

8. 8

   Every pipeline execution produces a trace log, regardless of success or failure. Traces are the primary observability artifact.

Observability model

Every pipeline execution is observable. Observability is not optional instrumentation — it is a first-class output of the execution system.

• Request IDs

  Each pipeline execution is tagged with a unique request ID generated at pipeline entry. All phase logs, validation failures, and render events reference the same ID.

• Phase logs

  Each phase emits start, completion, and error events. Phase duration is captured. If a pipeline halts, phase logs show exactly where execution stopped and the error that caused it.

• Pipeline trace

  A single structured log record per execution containing: registry contents at close, resolved field values with source decisions, validation results with structured failure data, render output reference, and total pipeline duration.

• Webhook tracing

  Incoming webhook events are logged with payload, handler resolution, and outcome. Replay tooling can re-execute a webhook event from its logged payload to reproduce handling behavior.

• Execution auditing

  Observability scripts aggregate trace logs across executions, surfacing patterns in validation failures, resolution conflicts, and render errors. Used for production debugging and regression analysis.

Failure model

Failures are explicit and phase-bound. No failure crosses phase boundaries silently. The system defines where failures are allowed, how they are surfaced, and what continues after them.

• Registration failure

  A field provider throws during registration. The field is excluded from the registry. Other fields are unaffected. The pipeline continues. Failure is logged with provider identity and error detail.

• Resolution failure

  A field's value cannot be resolved from any source. The field receives null. Validation rules for that field still run. Failure is logged. Pipeline continues.

• Validation failure

  One or more fields fail validation. Failures are collected as structured data: field key, rule name, message. The pipeline continues to Render. Render receives failure metadata alongside each affected field.

• Render failure

  Render throws while producing output. Control catches the error. The pipeline halts. No partial output is delivered. Failure is logged with the full pipeline trace.

• Output failure

  Control cannot deliver rendered HTML to WooCommerce output hooks. The pipeline falls back to WooCommerce's default rendering. Failure is logged. No silent fallback — the fallback path is explicit.

Operational tooling

FlxWoo ships operational tooling for production validation and debugging workflows.

• Smoke tests

  Pipeline integrity checks that verify all five phases execute correctly against a minimal known-good input set.

• Replay scripts

  Reproduce a past pipeline execution from its trace log. Used for deterministic reproduction of checkout failures.

• Deployment verification

  Scripts that confirm pipeline availability and configuration correctness after deployment or environment change.

• Cache verification

  Checks that checkout endpoints are excluded from page caches and CDN edge caches. Incorrect cache configuration is a common source of checkout state corruption.

• Observability scripts

  Aggregate and analyze execution traces for patterns in failures, resolution conflicts, and phase timing anomalies.

• WP-CLI diagnostics

  Command-line tools for inspecting registry state, running pipeline checks, and querying execution logs from the server environment.

Implementation reference

For integration details, API reference, operational tooling usage, and cache configuration, see the documentation.