Athenian FastPass for WooCommerce

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Customer Workflow

1. A shopper views a FastPass-eligible product.
2. The product page can display a FastPass badge and selector.
3. The shopper chooses standard processing, FastPass, or another configured option.
4. The selected option is captured when the item is added to cart.
5. In cart, the customer can review or toggle FastPass for eligible cart lines.
6. The plugin calculates the selected FastPass fees.
7. WooCommerce displays one consolidated FastPass Production fee in the cart totals.
8. Store API data remains available for block-based cart rendering or custom frontend logic.

Admin Workflow

1. Open a WooCommerce product in the admin.
2. Select the FastPass product-data tab.
3. Enable FastPass for the product.
4. Add a customer-facing label and description.
5. Choose a fee mode: percentage of line subtotal, fixed fee per line, or fixed fee per unit.
6. Enter the fee amount.
7. Optionally define minimum/maximum quantity and line-weight limits.
8. For variable products, review each variation and add variation-specific eligibility or overrides.
9. Save the product.
10. Review the product page and cart behavior to confirm the customer-facing flow.

Technical Architecture

Bootstrap

The root plugin file athenian-fastpass.php defines constants, registers a PSR-like autoloader for the Athenian\FastPass\ namespace, waits for WooCommerce to be available, and then boots Athenian\FastPass\Plugin::instance() on plugins_loaded.

Core Classes

| File | Class | Responsibility | | --- | --- | --- | | athenian-fastpass.php | Bootstrap | Plugin metadata, constants, autoloading, WooCommerce dependency check. | | includes/class-plugin.php | Athenian\FastPass\Plugin | Central service bootstrap. | | includes/class-admin-product-meta.php | Athenian\FastPass\Admin\Product_Meta | Product and variation admin fields. | | includes/class-cart-manager.php | Athenian\FastPass\Cart_Manager | Cart selection capture, session restoration, item display, fee calculation, cart UI. | | includes/class-ajax.php | Athenian\FastPass\Ajax | AJAX cart toggle handler. | | includes/class-assets.php | Athenian\FastPass\Assets | Frontend and admin asset loading. | | includes/class-shortcodes.php | Athenian\FastPass\Shortcodes | Product-page badge and selector shortcodes. | | includes/class-store-api.php | Athenian\FastPass\Store_API | WooCommerce Store API cart-item extension data. |

Loaded Services

Plugin::init() boots:

• Assets::boot()
• Cart_Manager::boot()
• Ajax::boot()
• Store_API::boot()
• Shortcodes::boot()
• Admin\Product_Meta::boot() when in admin context

WordPress and WooCommerce Hooks

Product/Admin Hooks

• woocommerce_product_data_tabs
• woocommerce_product_data_panels
• woocommerce_admin_process_product_object
• woocommerce_product_after_variable_attributes
• woocommerce_save_product_variation

Cart and Storefront Hooks

• woocommerce_add_cart_item_data
• woocommerce_get_cart_item_from_session
• woocommerce_get_item_data
• woocommerce_cart_calculate_fees
• woocommerce_after_cart_item_name
• woocommerce_single_product_summary
• woocommerce_before_add_to_cart_button

AJAX Hooks

• wp_ajax_afp_toggle_fastpass
• wp_ajax_nopriv_afp_toggle_fastpass

Blocks / Store API Hooks

• woocommerce_blocks_loaded
• woocommerce_store_api_register_endpoint_data() for cart item schema extension

Shortcodes

| Shortcode | Purpose | | --- | --- | | [afp_fastpass_badge] | Renders a product-level FastPass badge when the current product is eligible. | | [afp_fastpass_selector] | Renders a customer-facing FastPass selector with standard processing and available FastPass options. |

Selector Attributes

| Attribute | Default | Purpose | | --- | --- | --- | | show_badge | 0 | Optionally includes the FastPass badge inside the selector output. | | heading | FastPass | Custom heading text for the selector. |

Data Model

The plugin uses WooCommerce product and variation post meta rather than custom tables.

| Meta Key | Scope | Purpose | | --- | --- | --- | | _afp_fastpass_enabled | Product / variation | Enables FastPass eligibility. | | _afp_fastpass_label | Product / variation | Customer-facing FastPass label. | | _afp_fastpass_description | Product | Customer-facing FastPass description. | | _afp_fastpass_fee_mode | Product / variation | Fee calculation mode. | | _afp_fastpass_fee_amount | Product / variation | Percentage or fixed fee value. | | _afp_fastpass_min_qty | Product / variation | Optional minimum quantity rule. | | _afp_fastpass_max_qty | Product / variation | Optional maximum quantity rule. | | _afp_fastpass_min_weight | Product | Optional minimum line-weight rule. | | _afp_fastpass_max_weight | Product | Optional maximum line-weight rule. | | _afp_fastpass_options | Product | Optional JSON-encoded selector options. |

Cart Item Data

The cart manager supports both a legacy boolean selection flag and a newer option-key selection value.

| Cart Item Key | Purpose | | --- | --- | | afp_selected | Legacy boolean selection state used by existing cart UI and fee logic. | | afp_fastpass | Selected FastPass option key, such as fast or rush. |

This dual-key approach preserves existing checkbox behavior while leaving space for multi-option FastPass tiers.

Store API Data Contract

The Store API extension registers data under the PHP namespace identifier ath-fastpass and describes a cart-item schema containing:

{
  "eligible": true,
  "selected": true,
  "label": "FastPass production",
  "description": "Expedite production for this item, independent of shipping speed.",
  "fee_mode": "percent_line",
  "fee_amount": 10,
  "preview_fee": 4.25
}

This data is designed for WooCommerce Cart/Checkout Blocks and custom storefronts consuming Store API cart-item extension payloads.

Security and Validation Notes

The plugin includes several standard WordPress/WooCommerce safety patterns:

• Exits on direct access with ABSPATH checks.
• Boots only after WooCommerce is available.
• Uses nonces for AJAX cart toggles.
• Sanitizes product meta with sanitize_text_field(), wp_kses_post(), wc_clean(), wp_unslash(), and numeric casts.
• Validates cart item eligibility before allowing AJAX FastPass selection changes.
• Uses WooCommerce product APIs and cart APIs instead of direct database writes for cart behavior.

Integration Points

WooCommerce Product Catalog

FastPass eligibility and fee settings live on WooCommerce products and variations, making the feature catalog-aware without requiring a separate management interface.

WooCommerce Cart and Fees

The plugin integrates directly with WooCommerce cart item data, cart sessions, cart item display metadata, and cart fee calculation.

WooCommerce Blocks / Store API

The plugin exposes cart-item FastPass context through the Store API for block-based cart experiences and custom frontend integrations.

Athenian Platform Context

FastPass fits most naturally in the Athenian ecosystem as a commerce operations and production-expedite module, especially beside Print Forge, product add-ons, vendor routing, quote/cart builder, fulfillment, and shipment tooling. The bundled platform metadata currently categorizes it under customer identity/access tags, but the inspected code and source marketing material indicate that its real functional category is production, fulfillment, and WooCommerce cart monetization.