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

# Unified Commercial Suite architecture

> Runtime, interfaces, and data flow for the Unified Commercial Suite Shopify app.

# Unified Commercial Suite architecture

## Runtime

The embedded admin app runs on Cloudflare Workers with React Router 7 and Vite. Shopify sessions and B2B business data are stored in Cloudflare D1. A Cloudflare Queue and a Durable Object coordinate asynchronous customer-tag synchronization, and the queue also carries delayed privacy-export retries.

Shopify Admin GraphQL is the source of truth for catalog, customer, order, draft-order, and billing records.

## Interfaces and data flow

* **Admin routes** (`/app/*`) authenticate a verified Shopify admin session. Reads use the session; company and price-list mutations additionally require the account owner.
* **Admin APIs** (`/api/*`) authenticate the same Shopify session and return a consistent JSON envelope (`{ "success": true, "data": ... }` or `{ "success": false, "error": ... }`).
* **App proxy** (`/apps/b2b-toolkit`) is the signed storefront surface: pricing and quote requests, and the wholesale registration form. Shopify signs each forwarded request, so no tenant or customer identity is accepted from JavaScript.
* **Merchant API** (`/api/merchant/*`) is a separate Premium REST surface authenticated with a bearer key.
* **Webhooks** (`/webhooks`) accept `POST` only and verify Shopify's HMAC-SHA256 signature.

The storefront theme embed calls the signed pricing proxy and applies B2B unit prices for signed-in buyers. Draft-order checkout fetches authoritative variant, product, and collection data from Shopify Admin GraphQL and applies B2B pricing and order limits on the server.

## Checkout enforcement

Two Shopify Functions enforce B2B rules on standard checkouts alongside the manual draft-order path:

* **b2b-checkout-pricing** targets `cart.lines.discounts.generate.run`.
* **b2b-order-limits** targets `cart.validations.generate.run`.

The functions read app-owned JSON metafields in the `$app:pcnaid_b2b` namespace, hydrated from the backend, so policy is not merchant-editable through custom data. They validate time windows and company status so scheduled price lists and inactive companies behave correctly.

## Server libraries

| Area | Responsibility |
| - | - |
| D1 data access | Tenant-scoped repository for B2B, billing, webhook, and recovery entities |
| Pricing engine | Rule-based B2B price calculation with a specificity hierarchy |
| App-proxy HMAC | Signature validation for signed storefront requests |
| Billing | Plan definitions, entitlements, and subscription reconciliation |
| Customer sync DO | Per-shop/customer idempotent tag synchronization |
| Metafields | Projects company, customer, and price-list data into `$app` metafields and metaobjects |
| Merchant API / webhooks | API key generation, scope normalization, and signed outbound delivery with retries |

See the [API overview](https://docs.pcnaid.com/nodes/shopify/unified-commercial-suite/developer/api/index.md) for documented interfaces and the [quickstart](https://docs.pcnaid.com/nodes/shopify/unified-commercial-suite/developer/quickstart.md) to get oriented. For plain-English merchant instructions, see the [merchant guides](https://docs.pcnaid.com/nodes/shopify/unified-commercial-suite/merchant/guides/index.md).

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [Unified Commercial Suite](https://docs.pcnaid.com/nodes/shopify/unified-commercial-suite/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/unified-commercial-suite/developer/index)


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