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

# Loyalty & Rewards architecture

> Runtime stack, system architecture, and data flow for Loyalty & Rewards, grounded in the app's backend and frontend architecture docs.

# Loyalty & Rewards architecture

## Runtime stack

| Component | Technology |
| - | - |
| Framework | React Router 7 (Shopify React Router App Template) |
| Language | TypeScript 5.x (app), 7.x (extensions), strict mode |
| Admin UI | Polaris Web Components (`s-*`) + Pcnaid Design System + App Bridge |
| Database | PostgreSQL via Prisma 6.x |
| Cache / Rate limiting | Redis with in-memory fallback |
| Validation | Zod 4.x |
| Testing | Vitest 5.x |
| Email | Resend |
| SMS | Twilio |
| Error tracking | Sentry |
| Analytics | PostHog + Mixpanel |
| Bot protection | Cloudflare Turnstile |
| Short links | Shlink |
| Hosting | Containerized web service |

## System architecture

The app runs as an embedded Shopify app inside a Shopify Admin iframe. Shopify extensions provide storefront, customer-account, checkout, and POS surfaces. The React Router server handles admin routes (loaders + actions), app proxy endpoints (storefront API), webhook handlers, and POS API endpoints.

### Business logic services

* **Loyalty Service** — points ledger, earning rules engine, balance management.
* **Rewards Service** — discount code creation, redemption, reward catalog.
* **Referrals Service** — two-sided rewards, fraud prevention, click tracking.
* **Campaigns Service** — bonus-point campaigns with scheduling.
* **Communications** — email (Resend) and SMS (Twilio) notification dispatch.
* **Analytics Service** — KPI snapshots, cohort benchmarking.
* **Billing Service** — plan management, app-managed Shopify Billing API.
* **Event Bus** — domain event recording and outbound webhook delivery.
* **Fraud Detection** — velocity checks, duplicate account detection, risk scoring.
* **Store Credit** — Shopify native store credit synchronization.
* **Memberships** — paid membership programs.
* **Wallet Passes** — Apple Wallet and Google Wallet pass generation.
* **Social Rewards** — social media action rewards.
* **Tier Downgrade** — automated VIP tier demotion.
* **AI Advisor** — Cloudflare AI Gateway-powered recommendations.
* **Migration** — CSV import from competitor loyalty apps.

### Extensions

| Extension | Target | Purpose |
| - | - | - |
| Loyalty Theme Widgets | Theme blocks | Storefront: points, referrals, hub, popup, memberships, households, B2B, social rewards |
| Checkout Loyalty | `purchase.checkout.block.render` | Points redemption at checkout |
| POS Loyalty | `pos.customer-details.block.render` | Points display and redemption at POS |
| Customer Account Loyalty | `customer-account.page.render` | Loyalty hub in customer account |
| Flow Loyalty Triggers | 10 Flow triggers | Points, tier, referral, redemption automation |
| Flow Loyalty Actions | 6 Flow actions | Add/remove points, credits, assign tier, review reward |
| Loyalty Web Pixel | Web pixel extension | Storefront analytics event ingestion |

## Product data flow

The loyalty ledger records point activity in PostgreSQL. The app synchronizes loyalty data to Shopify metafields (95 definitions across customer, shop, product, collection, order) and metaobjects (13 types: reward definitions, VIP tiers, tier perks, achievements, missions, membership plans, bonus campaigns, popups, loyalty program settings, function config).

Theme code calls the signed `/apps/loyalty/*` app proxy. Shopify forwards the corresponding path to `/api/loyalty/*`. The storefront proxy API handles customer data, redemption, referrals, history, popups, social actions, wallet passes, SSE notifications, self-enrollment, visit tracking, and reviews.

## Data flow: order points award

When Shopify sends an `orders/paid` webhook, the webhook handler verifies the HMAC signature, checks idempotency, calculates points (with tier multiplier), creates a ledger entry, updates the customer balance, evaluates earning rules, detects velocity anomalies, evaluates VIP tier progression, evaluates achievements, and sends notifications.

## Data flow: reward redemption

Customers redeem rewards through the checkout, POS, or storefront extension. The endpoint validates authentication and points balance, deducts points, creates a Shopify discount code via GraphQL, persists the redemption record, and returns the discount code to the extension.

## Shopping data definitions

The app uses a single `$app` namespace for every metafield and metaobject. All 95 metafield definitions and 13 metaobject types are TOML-defined and auto-installed on `shopify app deploy`. Customer snapshots include 38+ fields covering points, tier state, referrals, and engagement counts. Customer tags (`loyalty-member`, `vip-{tier}`, `referrer`, `loyalty-opted-out`) are auto-managed.

[Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [Loyalty & Rewards](https://docs.pcnaid.com/nodes/shopify/loyalty-rewards/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/loyalty-rewards/developer/index) › Architecture overview › Loyalty & Rewards architecture


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