Skip to main content

​
GrowthAgent architecture

​
Runtime components

​
Authentication boundaries

  • Shopify OAuth — standard install flow at /auth/install and /auth/callback. OAuth state stored in KV with short TTL.
  • Embedded admin session — Shopify session tokens verified on every admin request. Session cookie fallback via /api/session/bootstrap with partitioned and unpartitioned cookies.
  • Public chat — rate-limited per-IP with KV-backed counters. Shop validation via request parameters. CORS-restricted.
  • Webhooks — HMAC signature verification before any handler logic.

​
Product data flow

  1. Store knowledge — merchant triggers catalog and policy sync through POST /api/knowledge/sync. Webhooks for products/create, products/update, products/delete, and inventory_levels/update signal content changes.
  2. Chat — storefront shopper message arrives at POST /chat. The Worker retrieves relevant knowledge, sends context to OpenAI Responses API, and returns the answer.
  3. Handoff — when the assistant identifies a support need, it sends notifications to the merchant-configured email (via Resend), SMS (via Twilio), fax (via Sinch), or webhook endpoint.
  4. Attribution — POST /webhooks/orders hashes the order’s cart_token, matches against stored conversation cart_token_hash, and records an assisted_order App Event.
  5. Simulation — runs within the Worker using saved settings. Does not publish theme changes or send real handoffs.

​
Privacy handling

Three Shopify compliance webhooks handled at POST /webhooks/privacy:
  • customers/data_request — exports customer data to R2 and emails the merchant a signed download link
  • customers/redact — deletes matching conversations, messages, handoff tickets, attribution events, and audit records
  • shop/redact — deletes all shop data including knowledge documents, usage events, and the shop record, with best-effort Algolia index cleanup
All handlers verify HMAC signature before processing. Concurrent work uses a claim-and-release pattern backed by an internal receipts table for idempotent delivery.

​
Infrastructure

​
Security model

  • Shopify OAuth HMAC, webhooks, and embedded-admin session tokens are verified.
  • Shop tokens and merchant-supplied OpenAI, Algolia, Twilio, and ElevenLabs credentials are AES-GCM encrypted before storage.
  • Public endpoints have shop validation, CORS restrictions, and KV-backed rate limits.
  • Mutating operations are auditable and constrained by the app-specific policy boundary.
  • The database uses a DML-only runtime role and a DDL-capable migration role, with ownership separated to a non-login role.

​
Merchant notes

For step-by-step setup, see the merchant guides. For the API surface, see the API overview.