Skip to main content

​
AgentLink architecture

​
Runtime

AgentLink runs on Cloudflare Workers with managed PostgreSQL behind a pooled connection binding. Cloudflare KV holds OAuth state and cache material. A SQLite-backed Durable Object handles atomic public-endpoint rate-limit counters. Cloudflare R2 stores encrypted snapshots and durable audit artifacts. The stack uses Hono as the web framework, Zod for input validation, and OpenAI Responses API for AI-generated remediation guidance. The embedded Shopify admin UI uses App Bridge and Polaris web components.

​
Data model

  • Shops — installed Shopify stores with subscription state, settings, and tenant identity.
  • Profiles — UCP agent profiles with payment handlers, policy schemas, signing keys, and public profile JSON.
  • Audits — readiness audit results with scores, findings, and AI remediation plans.
  • Traffic logs — MCP proxy request metadata including request/response SHA-256 hashes and AES-256-GCM encrypted replay bodies.
  • Usage events — plan-limited quota counters for audits, proxy requests, integrations, and agency dashboard views.
  • Backups — encrypted tenant-scoped R2 snapshots.
All tenant tables enforce PostgreSQL Row-Level Security with FORCE ROW LEVEL SECURITY. The application runtime authenticates with a least-privilege database role that is not a table owner and cannot bypass row-level security.

​
Security model

  • Shopify OAuth HMAC, webhooks, and embedded-admin session tokens are verified.
  • Shop tokens and BYOK AI keys are AES-256-GCM encrypted before storage.
  • Public endpoints have shop validation, CORS restrictions, and Durable Object rate limits.
  • Mutating operations are auditable and constrained by an app-specific policy boundary.
  • Content Security Policy restricts scripts to self, Shopify CDN, and a per-response nonce.
  • Tenant isolation is enforced at the database level; a cross-tenant read or write affects zero rows.

​
Embedded admin route map

The App Home sidebar declares five authenticated routes, all rendered by a nonce-protected embedded shell:
  • /app — Home: setup modal/banner flow, readiness summary, profile shortcut, 24-hour traffic count, and recent traffic table.
  • /app/billing — Plan & billing: plan selection, change, cancellation, trial guidance, and plan limits.
  • /app/readiness — Readiness audits: audit execution, findings, AI remediation, and OpenAI-key settings.
  • /app/profile — Agent profile: public-profile URL copy and profile configuration (payment handlers, policy schema, active status).
  • /app/support — Support: embedded email contact and safe-data guidance.

​
Public routes

AgentLink serves eight indexed public marketing pages plus discovery routes:
  • /start — Install and onboarding landing page.
  • /features — Feature depth covering UCP hosting, MCP proxying, readiness audits, schema drift, and proxy audit logs.
  • /trust — Security and trust architecture.
  • /partners — Partner ecosystem.
  • /pricing — Transparent Shopify billing plans (Foundation, Growth, Scale) with 14-day free trials.
  • /support — Merchant support contact and safe data practices.
  • /legal/cookies — Cookie notice.
  • /legal/accessibility — Accessibility statement.

​
Discovery and proxy routes

  • /.well-known/ucp?shop=<domain> — Public UCP profile with ECDSA P-256/SHA-256 signature.
  • /ucp/:shop/.well-known/ucp — Path-style public UCP profile.
  • /mcp/:shop/storefront and /mcp/:shop/ucp — Durable, rate-limited MCP proxy endpoints.
  • /schema/:shop.json — Schema.org product feed from Admin GraphQL.
  • /llms.txt?shop=<domain> — Public llms.txt index for AI tools.

​
Shopify integration

  • Scopes: read_products, read_inventory, read_legal_policies.
  • Webhook topics: app/uninstalled, app_subscriptions/update, products/create|update|delete, inventory_levels/update, shop/update, plus mandatory compliance topics (customers/data_request, customers/redact, shop/redact).
  • Billing: Shopify subscriptions with three plan tiers. New shops receive one 14-day trial.

​
Data retention

​
Observability

AgentLink uses PostHog (product analytics), Sentry (error tracking), and Datadog (log events). Deployment verification confirms delivery to all three vendors. The GET /healthz endpoint reports the release SHA for deployment verification. See the merchant guides for the store-facing workflow and the API overview for documented interfaces. Pcnaid Documentation › Shopify Ecosystem › AgentLink › Developer