Product Overview & Architecture — RUTHH COD Form & Upsells

Understand the core subsystems of RUTHH COD Form & Upsells, how changes saved in your Shopify Admin are published to your storefront via revision-locked metafield snapshots, and how the server validates and prices every Cash on Delivery order.

• A Shopify store running an Online Store 2.0 compatible theme.
• Staff or store owner permissions capable of viewing apps, themes, and orders in Shopify Admin.

When you open RUTHH COD Form & Upsells inside Shopify Admin, the navigation is organized into eight workspaces:

1. Home (/app): Onboarding checklist, live Theme App Embed status badge, and KPI summary (Form Opens, Orders or Orders / Draft Orders, Conversion Rate, Revenue, AOV) filterable by 24h, 7d, 14d, or 30d.
2. Form Builder (/app/form-builder):
   • Form Designer (/app/form-builder): Field layout, required/visible rules, country/province/district cascade, visual presets, button icons/animations, RTL/LTR direction, and custom CSS.
   • Shipping Rates (/app/form-builder/shipping-rates): Conditional COD shipping rates and 1-click Shopify Shipping profile import.
   • Thank You Page (/app/form-builder/thank-you): Post-order modal content and after-purchase redirect behavior.
3. Sales Booster (/app/sales-booster):
   • Quantity Offers (/app/sales-booster/quantity-offers): Tiered volume discounts (ACTIVE).
   • Bundles (/app/sales-booster/bundles): Multi-item product bundles (ADMIN & V2 SNAPSHOT READY).
   • One-Tick Upsells (/app/sales-booster/one-tick-upsells): Product upsells and independent service fees (ADMIN & V2 SNAPSHOT READY).
   • Downsells (/app/sales-booster/downsells): Cancel-intent discount modals (ACTIVE).
   • Post-Purchase Upsells (/app/sales-booster/post-purchase-upsells): Post-order one-click upsells (PILOT GATED via POST_PURCHASE_RUNTIME).
4. Fraud Protection (/app/fraud): User Blocking velocity limits, duplicate order detection, max product quantity caps, phone/email/IP blocklists, and trusted IP allowlists.
5. Integrations (/app/integrations):
   • Google Sheets (/app/integrations/google-sheets): Real-time order and line-item export via OAuth drive.file.
   • SMS & WhatsApp (/app/integrations/messaging): Phone OTP and WhatsApp confirmation workspace (live sends gated pending external provider activation).
6. Analytics (/app/analytics): Funnel progression (cod:form_open, cod:form_submit, cod:order_created) and revenue breakdown.
7. Settings (/app/settings):
   • Visibility (/app/settings): Surface rules, Popup vs Embedded mode, native button hiding, product/collection targeting, and subtotal bounds.
   • General (/app/settings/general): Standard Order vs Draft Order mode, default tags, UTM forwarding, Additional COD Fee, after-purchase actions, and alert contacts.
   • Pixels (/app/settings/pixels): Meta Pixel + CAPI, TikTok Pixel + Events API 2.0, GA4, Google Ads, and Pinterest Tag.
8. Pricing (/app/pricing): Plan tiers (Free, Basic, Growth, Unlimited), cycle order usage, and 24-hour grace status.

1. Save in Admin: When you modify settings in Form Designer, Visibility, Shipping Rates, or Sales Booster, the Shopify App Bridge SaveBar appears. Clicking Save writes the validated configuration to PostgreSQL and increments its monotonic revision number.
2. Transactional Snapshot Projection: A background publication worker serializes the active configuration into compact JSON snapshots stored on your AppInstallation metafields (each capped at 120 KiB max):
   • cod_form.v2_snapshot (storefront-form/v1 — form fields, styling, visibility, and optional additionalCodFee)
   • cod_shipping.v1_snapshot (shipping-config/v1 — conditional COD shipping rates)
   • cod_offers.v1_snapshot (quantity-offer/v1 — active quantity offer tiers)
   • cod_downsell.v1_snapshot (downsell/v1 — cancel-intent downsell modal)
   • cod_boosters.v1_snapshot (sales-booster/v2 — bundles and one-tick upsells/fees)
   • cod_thank_you.v1_snapshot (thank-you/v1 — in-modal confirmation view)
3. Instant Storefront Bootstrap: Your storefront theme reads these metafields directly through the cod-app-embed.liquid App Embed without blocking page rendering.
4. Server-Authoritative Admission: When a buyer requests a cart quote (POST /app-proxy/cart-quote) or submits an order (POST /app-proxy/order-intents), the server checks that submittedFormConfigRevision matches the active revision, re-evaluates product/collection eligibility, calculates discounts and fees in integer minor units of your shop currency, and creates the Shopify Order or Draft Order.

• Saved changes do not appear immediately on the storefront: Refresh the storefront page after the SaveBar completes. If a buyer had an older tab open before you saved, submitting that stale tab triggers a FORM_CONFIG_REVISION_MISMATCH response instructing the form to reload the latest configuration.
• KPI cards show Orders / Draft Orders: This label appears automatically when your store is configured to use Save as Draft Order mode in Settings → General or when historical draft orders exist in the selected date window.

• Installation & Theme App Embed Setup
• Visibility & Display Rules
• Order Creation Modes & Google Sheets Export