> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GrowthAgent quickstart

> Get oriented as an integrator or contributor — installation, scopes, extensions, and first steps.

# GrowthAgent quickstart

## What is GrowthAgent?

GrowthAgent (App Store listing name; the app code uses **Storefront Agent**) is a Shopify app that helps shoppers find products, get cart guidance, and understand store policies through a storefront AI assistant. It runs on Cloudflare Workers with PostgreSQL, OpenAI, and optional ElevenLabs, Twilio, Resend, Sinch, and Algolia integrations.

## Shopify app details

| Field | Value |
| - | - |
| App name | GrowthAgent |
| API version | `2026-04` |
| Embedded | Yes |

## OAuth scopes

```
read_products, read_content, read_orders, read_customers,
write_discounts, read_inventory, read_legal_policies
```

**7 scopes total.** `read_legal_policies` enables knowledge sync to read shop refund, privacy, shipping, and terms policies. `read_customers` is gated off in chat — the assistant filters out customer, order, account, return, and refund MCP tools. `read_themes` is intentionally not requested to avoid forced OAuth re-consent for merchants.

## Theme extension

**Storefront Agent Chat** (`storefront-chat`) — a single theme app embed block (`chat-widget.liquid`, target `body`) with four settings: `enabled`, `worker_endpoint`, `title`, `position`. Works with OS 2.0 (JSON templates) and vintage (Liquid) themes.

## Webhook topics

11 topics total: `app/uninstalled`, `app_subscriptions/update`, `products/create`, `products/update`, `products/delete`, `inventory_levels/update`, `orders/create`, `shop/update`, plus three compliance topics (`customers/data_request`, `customers/redact`, `shop/redact`).

## First steps

1. **Read the architecture overview** — understand the runtime, data flow, and component boundaries.
2. **Review the API reference** — learn the public endpoints for chat, health, and the embedded admin API.
3. **Set up a development environment:**
   * Clone `PcnaidInc/storefront-revenue-agent`
   * Run `pnpm install`
   * Provision Cloudflare resources: `pnpm provision:cloudflare`
   * Run migrations: `pnpm migrate`
   * Start local Wrangler dev: `pnpm dev`

## Key commands

```bash theme={null}
pnpm dev                       # local Wrangler dev
pnpm typecheck                 # TypeScript checks
pnpm test                      # shared package + app tests
pnpm migrate                   # apply database migrations
pnpm generate:shopify-config   # generate Shopify app TOML
pnpm provision:cloudflare      # provision Cloudflare resources
pnpm deploy                    # deploy the Worker
```

## Repository layout

```
apps/storefront-agent/          # Worker source
  src/index.ts                  # app entry point
  shopify.app.toml              # Shopify app configuration
  wrangler.toml                 # Cloudflare Worker config
  extensions/
    storefront-chat/            # theme app extension
packages/shared/                # shared library
  src/shopify.ts                # OAuth, webhooks, privacy
  src/mcp.ts                    # MCP tools
  src/email.ts                  # Resend integration
supabase/migrations/            # database migrations
scripts/                        # Cloudflare provisioning
.github/workflows/              # CI and deploy
```

## Sign-in model

The app uses Shopify OAuth for merchant authentication (standard install flow). Embedded admin pages use Shopify session tokens. Public chat endpoints are rate-limited per-IP and shop-validated.

The [API overview](https://docs.pcnaid.com/nodes/shopify/growthagent/developer/api/index.md) documents the externally reachable surface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.