code-redemption-platform

private

A production redemption platform for a limited-run brand collaboration. Customers verify their Shopify identity, phone number, and proof of purchase before exchanging a retail product code for a unique game access code.

Node.jsTypeScriptExpressPostgreSQLRedisBullMQShopify Admin APITwilioMailgunSentryAWSEC2RDSECR

cat architecture.md

AWS Infrastructure

EC2 application hosting
ECR container image registry

Shopify Customer Flow

Customer authentication
Product code entry
Redemption status

Express API

Request authentication
Code validation
Redemption orchestration

Twilio SMS OTP

Phone verification
One-time passcode delivery
OTP expiration

Purchase Verification

Shopify order lookup
Amazon and retail order validation
Receipt upload fallback

PostgreSQL on RDS

Product code inventory
User and redemption records
Atomic code claiming
Prevents double-redemption

Redis and BullMQ

Asynchronous redemption jobs
Shopify webhook processing
Receipt validation service integration jobs
Retries and queue monitoring

Mailgun

Redemption confirmation
Game access code delivery
Redemption receipt

Shopify and Receipt Validation Webhooks

Automatic redemption after order fulfillment
Receipt review status updates
Webhook signature validation

# Why multiple verification layers?: A product code alone is not enough to authorize a redemption. The platform combines Shopify customer authentication, SMS verification, and proof of purchase to ensure that codes are redeemed by legitimate customers and to limit abuse.
# Why support multiple proof-of-purchase paths?: Customers may purchase through Shopify, Amazon, Walmart, or another retail channel. The platform verifies Shopify orders automatically, validates eligible retail orders against imported records, and routes unmatched customers to a receipt validation service for receipt-based review.
# Why use background queues?: Shopify webhooks, fulfillment processing, and external API calls can arrive in bursts or fail temporarily. BullMQ and Redis isolate those operations from the customer-facing API, provide retry handling, and keep redemption processing reliable during campaign traffic spikes.
# How are duplicate redemptions prevented?: Product codes and access codes are stored with unique constraints and redemption state in PostgreSQL. Codes are claimed atomically so concurrent requests cannot redeem the same inventory more than once.