Architecture

Data Flow

AutoCart operates across three Shopify surfaces, each with different capabilities and constraints:

1. Storefront (Theme Extension)

The theme extension runs on every storefront page load. It:

• Reads your automation rules
• Populates window.autoCartConfig with all rule data, product info, and settings
• Intercepts cart API calls (/cart/add, /cart/change, optionally /cart/update)
• Evaluates rules against the current cart state
• Displays gift picker modals when rules match

Key constraint: The storefront extension cannot access customer tags or checkout-specific data (payment method, shipping address).

2. Checkout (Checkout Gift Extension)

The checkout extension re-evaluates rules with richer context:

• Accesses customer identity, tags, and company info
• Reads delivery groups and shipping addresses
• Evaluates payment method conditions
• Can apply discount codes programmatically
• Manages a queue for sequential cart mutations

Key behaviors:

• Auto-clean: Removes products from expired or deleted rules
• Scope filtering: Only evaluates rules scoped to checkout or global (not storefront-only)
• doNotEvaluateStorefrontRule: Optionally preserves products added by storefront-only rules

3. Discount Function

The discount function runs server-side on Shopify's infrastructure:

• Reads cart line attributes to determine which discounts to apply
• Applies product-level discounts as configured
• Runs on every checkout calculation
• No network access — purely input/output based

Rule Evaluation

Rules are evaluated using a conditions engine. The evaluation flow:

Automation Rule
        │
        ▼
  Build Input Object
  (cart lines, cost, customer, attributes, discounts, delivery groups)
        │
        ▼
  Evaluate conditions against input
        │
        ├── true  → Add/keep products, apply discounts
        └── false → Remove products (if keep=false)