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

# Customer Gate architecture

> Runtime and product data flow for the Customer Gate Shopify app.

# Customer Gate architecture

## Runtime

Customer Gate runs as a Cloudflare Worker named `pcnaid-customer-gate`, with `apps/customer-gate/src/index.ts` as its entry point. It is a Shopify app with embedded admin, OAuth, App Bridge ID-token verification, staff-level online-token authorization, verified webhooks, and audit logging.

PostgreSQL is accessed through a pooled connection binding and stores installed-shop sessions, Shopify token state, and application data. Object storage holds supporting documents, and a key-value store provides rate limiting.

Shopify scopes are `read_customers,write_customers,read_companies,write_companies,write_validations`.

## Product data flow

The theme block loads a published form through the `/apps/customer-gate` Shopify app proxy. Payloads are checked against the published schema before storage. After submission and after each document upload, approval rules run in priority order and can approve, deny, request revision, add Shopify customer tags, create Shopify B2B company records, grant entitlements, and send email/SMS updates. Matched decisions drive Shopify tags and metafields plus persisted entitlements.

Access rules evaluate entitlements and Shopify tags for storefront, product, collection, customer-account, and checkout surfaces. Checkout enforcement runs in the checkout validation function and fails closed when required customer state is absent. The theme gate and the customer-account extension surface the access decision.

## Extensions

The app ships three extensions:

* **theme-access-gate** — a theme app extension with two blocks: `access-gate` (Customer Gate message) and `application-form` (Customer Gate form).
* **customer-portal** — a customer-account UI extension for authenticated application status, login-required form submission, optional document upload, and the access decision.
* **checkout-access-validation** — a checkout validation function that enforces checkout access at `cart.validations.generate.run`.

## Public surfaces

Public routes serve the storefront form and access APIs, and the `/support`, `/docs`, and `/documentation` HTML surfaces. The privacy policy and terms of service are hosted on docs.pcnaid.com, with `/legal/privacy`, `/privacy`, `/legal/terms`, and `/terms` issuing permanent 301 redirects. `/health` reports liveness and `/healthz` additionally proves a database query and returns `database: "ok"`.

See the [API overview](https://docs.pcnaid.com/nodes/shopify/customer-gate/developer/api/index.md) for documented interfaces and the [quickstart](https://docs.pcnaid.com/nodes/shopify/customer-gate/developer/quickstart.md) for orientation.


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