This repository is a reference architecture showcase extracted from a real production WooCommerce extension.
It focuses on architectural decisions, execution boundaries, and operational behavior — not on business-specific logic or proprietary implementation details.The corresponding business and delivery context is described in the dedicated case study:
👉 https://rocketdeploy.dev/en/case-studies/woocommerce-order-status-manager
This Plugin extends WooCommerce order-status operations in the admin area.
Its core responsibility is to allow store staff to define, reorder, import, export, and present order statuses while preserving compatibility with platform-native status flows.
The architecture follows a procedural, hook-driven model aligned with WordPress runtime principles:
- A bootstrap stage wires modules and registers hooks
- Admin handlers process operator actions
- A normalization layer validates and canonicalizes input
- A storage layer persists configuration
- An integration adapter projects stored state back into WooCommerce behavior
The design intentionally stays within platform boundaries and avoids invasive runtime mutations.
- Operator / Store staff interacting with the Admin UI
- WordPress runtime providing lifecycle hooks, nonce utilities, capability APIs, options/transients storage, and AJAX routing
- WooCommerce runtime consuming status registration and status-list filtering hooks
- Operator uses the Order screen settings area.
- Admin UI submits actions to nonce-protected handlers.
- Handlers apply capability gates and sanitize payloads.
- Normalized state is written to the configuration store.
- Integration hooks rehydrate runtime status behavior from persisted state.
Recommended reading sequence for reviewers:
- Bootstrap entry point — lifecycle wiring and hook registration.
- Admin page renderer + action handlers — UI routing, POST handling, capability checks.
- AJAX reorder endpoint — authenticated async reorder flow.
- Import/export pipeline — upload, preview, apply, export path.
- Persistence adapter — normalization and option/transient usage.
- Integration adapter — projection of persisted state into WooCommerce runtime.
Admin UI (settings tab + wizard + drag/drop)
│
▼
Nonce-protected handlers + Capability gate
│
▼
Configuration normalizer (sanitize, validate, canonicalize)
│
▼
Storage layer (options + transient session token)
│
▼
Platform integration hooks (status registration, status lists, admin badges)
- Manage custom status definitions and metadata for built-in statuses
- Control ordering and admin visibility behavior
- Import/export configuration snapshots
- Provide synchronous form handlers and asynchronous reorder handling
- No custom database tables
- No mutation of WooCommerce core schemas
- No checkout/cart/payment pipeline modifications
- No storefront rendering concerns
Runtime authority remains with WordPress/WooCommerce; this Plugin contributes configuration and hook-based overlays only.
- Loads module set
- Registers lifecycle hooks and filters
- Declares compatibility flags early in initialization
- Adds dedicated settings tab
- Routes between sections (status management, add-new, import/export)
- Uses action-based form handling rather than settings API saves
- Guarded by nonce + capability checks
- Support create/update/delete operations
- Persist normalized state only
- Authenticated admin AJAX entry
- Validates membership and remaps sequence values
- Persists atomically at option level
- Export path validates capability and streams downloadable artifact
- Import path performs upload validation, schema checks, preview generation, and conflict-aware apply
- Uses short-lived tokenized transient state between preview and apply
- Reads/writes configuration via platform options
- Normalizes labels, locale maps, booleans, order values, and color values
- Performs defensive repair when stored state is partially malformed
- Registers custom statuses
- Rebuilds effective status ordering
- Injects admin integrations (bulk actions, badge output, dropdown filtering)
Integration is hook-first and side-effect constrained:
- Initialization hooks register statuses and load localization
- Admin hooks attach asset loading and form/export handling
- Filter hooks rewrite effective status arrays
- AJAX hook exposes reorder behavior
A guard flag prevents recursive status-fetching loops when integration code reads filtered WooCommerce status data.
- Entry defines constants and compatibility callback
- Modules load
- Hook map registers for lifecycle and admin events
- Operator submits form
- Nonce + capability validated
- Payload sanitized and normalized
- Configuration store updated
- Admin notice returned
- UI computes ordered identifiers
- Client posts via AJAX
- Endpoint validates
- Sequence values remapped
- JSON response returned
- Operator triggers export
- Capability + nonce validated
- Payload built
- File streamed
- Upload validated
- JSON parsed and schema-checked
- Transient token created
- Preview generated
- Apply merges state deterministically
- Configuration store (options):
- Custom status definitions
- Built-in status metadata
- Transient import session keyed by token
- Canonical slug sanitization
- Locale-aware normalization with fallback
- Color normalization to constrained hex format
- Integer coercion and stable sorting
- Self-healing re-save on repairable inconsistencies
- Strict schema validation for imports
- Early rejection of malformed uploads
- Explicit error notices for UI
- Structured JSON responses for AJAX
- Idempotent conflict handling in import
- Guardrails against unknown identifiers during reorder/merge
Security is enforced at every mutation entrypoint:
- Capability gate for privileged operations
- Nonce validation for forms and AJAX
- Input sanitization before persistence
- Escaped output in admin templates
- Request scoping for context routing
Aligns with WordPress runtime model and minimal bootstrap overhead.
Trade-off: requires naming discipline and clear modular separation.
Simplifies deployment and uninstall lifecycle.
Trade-off: relies on normalization discipline and bounded payload sizes.
Improves operator safety and conflict transparency.
Trade-off: introduces transient session management complexity.
Prevents client drift and enforces canonical state.
Trade-off: more transformation logic on write paths.
Improves UX responsiveness while preserving deterministic validation.
Trade-off: requires consistency across validation channels.
- Confirm capability + nonce checks on all mutation paths
- Verify normalization invariants before persistence
- Validate import parser robustness against malformed payloads
- Inspect conflict-resolution semantics
- Confirm reorder stability and recursion guards
- Ensure escaped rendering in admin output
Maturity indicators:
- Clear separation of UI, storage, and integration projection
- Deterministic import/export lifecycle
- Support for both built-in metadata and custom definitions
Potential future evolution:
- Shared validator utilities to reduce duplicated checks
- Expanded integration-level test fixtures
- Gradual encapsulation of procedural modules with domain-oriented wrappers
The production implementation of this architecture is publicly available in the plugin repository:
👉 https://github.com/rocketdeploy-dev/woocommerce-order-status-manager
This repository contains:
- the complete plugin source code,
- release history,
- packaging workflows,
- and the production-ready artifact used in real deployments.
The showcase focuses on architectural structure.
The plugin repository demonstrates the implementation.
This architecture reflects how rocketdeploy approaches operational tooling:
structured, platform-aligned, and execution-disciplined.
If you are designing or extending WooCommerce-based operational systems and need architectural review or implementation support:
👉 https://rocketdeploy.dev/en/contact
Built and maintained by rocketdeploy.