Architecture Overview

Runtime Shape

UpsellBay is a WooCommerce-native offer engine. Its runtime code lives under app/ and uses the namespace WPAnchorBay\UpsellBay.

The plugin follows a small-service architecture:

• upsellbay.php Loads the plugin, runs environment checks, and starts the bootstrap.
• app/Core/Plugin.php Coordinates service registration, WordPress hooks, and module startup order.
• app/Core/Container.php Provides a lightweight dependency container for runtime services.

Main Modules

• Core Shared identifiers, bootstrap, settings, installer, scheduler, and hook helpers.
• Admin WooCommerce admin screens such as Offers, Settings, Tools, Help, and Wizard.
• Api REST route registration and controller classes.
• Data Repositories and session storage adapters.
• Domain Business logic for offers, rules, discounts, storefront rendering, analytics, attribution, cart mutation, logging, and compatibility checks.
• Integrations WooCommerce-specific integrations such as Block Checkout and licensing.
• Utils Cross-cutting helpers including rate limiting, token handling, and import/export.

Storefront Flow

At runtime, UpsellBay follows this path:

1. An offer is loaded from the private upsellbay_offer CPT.
2. Rules and schedule checks determine whether the offer is eligible.
3. A placement renderer builds escaped storefront HTML for classic WooCommerce contexts.
4. Public REST routes handle accept and dismiss actions using a plugin-issued session token.
5. Attribution and aggregate analytics are written server-side.

Block Checkout support follows the same business rules, but uses WooCommerce Blocks integration points instead of classic PHP render hooks.

Public vs Private Contract

External developers should treat these as the supported integration surface:

• Documented hooks and filters
• REST routes under upsellbay/v1
• Shared identifiers from Core\Constants
• Offer export/import JSON shape

Avoid coupling to:

• The internal container wiring
• Admin page markup or CSS selectors
• Private class construction details
• Direct database writes outside documented storage contracts