> ## 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 architecture

> Runtime components, data flow, authentication, privacy handling, and infrastructure for GrowthAgent.

# GrowthAgent architecture

## Runtime components

| Component | Role |
| - | - |
| **Cloudflare Worker** | Hosts the app backend on Cloudflare Workers. Handles embedded admin routes, public chat endpoints, webhooks, OAuth, billing, and privacy operations. |
| **PostgreSQL** | Managed PostgreSQL behind a pooled connection binding. Each shop's data is tenant-scoped through RLS. |
| **Cloudflare KV** | OAuth state (short TTL), rate-limiting counters, and cache material. Two namespaces: one for OAuth state, one for cache material. |
| **Cloudflare R2** | Privacy export artifacts (download-link objects) and durable audit artifacts. |
| **Theme app extension** | `storefront-chat` — one app embed block (`chat-widget.liquid`, target `body`) with four schema settings (`enabled`, `worker_endpoint`, `title`, `position`). Works with Online Store 2.0 (JSON templates) and vintage (Liquid) themes. |
| **Shopify Admin API** | OAuth flow, Admin GraphQL queries, Shopify App Events for usage metering. |

## 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

| Resource | Binding |
| - | - |
| Compute | Cloudflare Worker |
| Database | Managed PostgreSQL through a pooled connection binding; migrations use a separate direct connection |
| KV | OAuth state namespace, cache namespace |
| Object storage | R2 bucket for privacy exports |
| AI | OpenAI Responses API (managed or merchant-supplied key) |
| Voice (optional) | ElevenLabs Text-to-Speech |
| Email (optional) | Resend |
| SMS (optional) | Twilio |
| Fax (optional) | Sinch Fax v3 |
| Search indexing (optional) | Merchant-supplied Algolia |
| Observability | Sentry (errors), PostHog (events), Datadog (diagnostics) |

## 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](https://docs.pcnaid.com/nodes/shopify/growthagent/merchant/guides/index.md). For the API surface, see the [API overview](https://docs.pcnaid.com/nodes/shopify/growthagent/developer/api/index.md).


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