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

# POS True Retail Operations Suite architecture

> Runtime components, request flow, data storage, authentication boundaries, POS extensions, and webhooks.

# POS True Retail Operations Suite architecture

## Runtime components

| Component | Responsibility |
| - | - |
| Cloudflare Worker (Hono) | Serves the authenticated API, OAuth flow, webhooks, and static frontend assets |
| D1 (SQLite) | Operational records, audit events, sessions, location configuration, inventory audits, and billing state |
| Workers KV | OAuth/dev state and legacy location-read compatibility only |
| React embedded admin (Vite + Polaris) | App Home, settings, catalog, audit, billing, operations, and retail workflow pages |
| Shopify POS UI extensions | Price adjustment, void transaction, store credit, and retail workflows |
| Shopify Admin GraphQL (`2026-01`) | Voids, store credit, locations, inventory, metafields, and metaobjects |

The Worker also exposes public release-identity endpoints (`/healthz`, `/release.json`) and permanent redirects from the old `/privacy` and `/terms` app-host paths to the shared documentation site.

## Request flow

Every authenticated API request follows the same middleware pipeline:

```text theme={null}
Request → Error handling → Logging → CORS → Security headers (CSP) → Auth (JWT) → Rate limiting → Route handler
```

Session tokens are JWTs signed with HMAC-SHA256 using the app secret. The shop tenant comes only from the verified `dest` claim; a query-string shop is never trusted. Mutation endpoints are rate-limited per shop at 50 requests per minute using atomic D1 counters. Privileged routes exchange the session token for an expiring online access token and enforce the acting staff member's scopes; account-wide settings and billing mutations are account-owner only. Anonymous or invalid identity returns `401`; an authenticated user without permission returns `403`.

Mutating operations accept an idempotency key. The key and its response are stored in D1, and a duplicate request returns the cached response; keys expire after seven days.

## Data storage

D1 holds the application's tenant-scoped tables, including `audit_events`, `idempotency_keys`, `sessions`, `location_configs`, `rate_limit_counters`, the billing tables (`shop_subscriptions`, `shop_entitlements`, `shop_trial_history`), the inventory-audit table, and the retail-workflow tables (`retail_workflow_records`, `retail_feature_settings`, `retail_webhook_subscriptions`, `retail_webhook_deliveries`). Every tenant table uses `shop` as the leading primary-key column, preserving cross-shop isolation.

Workers KV is limited to OAuth/dev state and legacy location-read fallbacks. Canonical location configuration lives in D1.

Shopify metafields (via the `$app` namespace) hold catalog attributes on products and variants, while metaobjects hold stable retail policies.

## POS extensions

Four production POS UI extensions use the current POS UI extension runtime (Preact TSX modules, POS web components, `shopify.extension.toml` with `type = "ui_extension"`, `api_version = "2026-10"`):

| Extension | Targets | Backend endpoint |
| - | - | - |
| Price Adjustment | Smart Grid tile/modal plus cart line-item action | `POST /api/price-edits/log` |
| Void Transaction | Smart Grid tile/modal plus order action | `GET /api/voids/eligible`, `POST /api/voids` |
| Store Credit | Smart Grid tile/modal plus customer action | `POST /api/store-credit/issue` |
| Retail Workflows | Smart Grid tile/modal | `GET /api/retail/capabilities`, `POST /api/retail/workflows/:capability` |

Each extension calls the location settings or retail capabilities endpoint and fails closed when it cannot verify access. Backend authorization is repeated before every operation.

A fifth package, the receipt-footer renderer, is built and typechecked but excluded from the production app configuration because Shopify classifies `pos.receipt-footer.block.render` as developer preview. It is not part of a production Shopify app version.

## Webhooks

The app declares six Shopify webhook subscriptions in `shopify.app.toml`: `app/uninstalled`, `app_subscriptions/update`, `shop/update`, and the three mandatory GDPR compliance topics `customers/data_request`, `customers/redact`, and `shop/redact`. Every route verifies the HMAC-SHA256 signature over the raw body before processing and claims the delivery ID in D1 to suppress duplicates. See [Webhooks](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/webhooks/index.md) for topics and handling.

## Billing

Billing is app-managed through Shopify's Billing API, driven from the in-app Plans & billing page. The plan catalog is the source of truth, and the Worker enforces each operation's minimum tier.

See the [API overview](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/api/index.md) for the externally reachable surface and the [quickstart](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/quickstart.md) to get oriented.

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [POS True Retail Operations Suite](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/pos-true-retail-operations/developer/index)


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