Design a Flash Sale System

7 collapsed lines
1
interface QueueStatus {
2
  status: "waiting" | "admitted" | "expired"
3
  position?: number
4
  estimated_wait_seconds?: number
5
  checkout_url?: string
6
  poll_interval_seconds: number
7
}
8

9
async function pollQueueStatus(ticket: string): Promise<void> {
10
  const response = await fetch(`/api/v1/queue/status/${ticket}`)
11
  const status: QueueStatus = await response.json()
12

13
  switch (status.status) {
14
    case "waiting":
15
      updateUI(status.position, status.estimated_wait_seconds)
16
      // Exponential backoff near front of queue
17
      const interval = status.poll_interval_seconds * 1000
18
      setTimeout(() => pollQueueStatus(ticket), interval)
19
      break
20

21
    case "admitted":
22
      showRedirectNotice()
23
      // Small delay for user to see the message
24
      setTimeout(() => {
25
        window.location.href = status.checkout_url
26
      }, 1500)
27
      break
28

29
    case "expired":
30
      showExpiredMessage()
31
      break
32
  }
33
}
34

35
// Start polling on page load
36
const ticket = new URLSearchParams(window.location.search).get("ticket")
37
if (ticket) {
38
  pollQueueStatus(ticket)
1 collapsed line
39
}

14 collapsed lines
1
import { DynamoDB } from "@aws-sdk/client-dynamodb"
2
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb"
3

4
const ddb = DynamoDBDocument.from(new DynamoDB({}))
5

6
interface QueueEntry {
7
  sale_id: string
8
  queue_ticket: string
9
  user_id: string
10
  position: number
11
  status: "waiting" | "admitted" | "expired" | "completed"
12
  checkout_token?: string
13
}
14

15
export async function joinQueue(
16
  saleId: string,
17
  userId: string,
18
  deviceFingerprint: string,
19
): Promise<{ ticket: string; position: number }> {
20
  // Check if user already in queue
21
  const existing = await findUserInQueue(saleId, userId)
22
  if (existing) {
23
    return { ticket: existing.queue_ticket, position: existing.position }
24
  }
25

26
  // Get current queue length (approximate, for position)
27
  const position = await getNextPosition(saleId)
28

29
  const ticket = generateTicket()
30

31
  await ddb.put({
32
    TableName: "FlashSaleQueue",
33
    Item: {
34
      sale_id: saleId,
35
      queue_ticket: ticket,
36
      user_id: userId,
37
      position: position,
38
      status: "waiting",
39
      joined_at: new Date().toISOString(),
40
      device_fingerprint: deviceFingerprint,
41
      ttl: Math.floor(Date.now() / 1000) + 3600, // 1 hour TTL
42
    },
43
    ConditionExpression: "attribute_not_exists(queue_ticket)",
44
  })
45

46
  return { ticket, position }
47
}
48

49
export async function admitNextUsers(saleId: string, count: number): Promise<void> {
50
  // Invoked by EventBridge at fixed rate (e.g., every second)
51
  // Admits 'count' users from front of queue
52

53
  const waiting = await ddb.query({
54
    TableName: "FlashSaleQueue",
55
    IndexName: "sale_id-position-index",
56
    KeyConditionExpression: "sale_id = :sid",
57
    FilterExpression: "#status = :waiting",
58
    ExpressionAttributeNames: { "#status": "status" },
16 collapsed lines
59
    ExpressionAttributeValues: {
60
      ":sid": saleId,
61
      ":waiting": "waiting",
62
    },
63
    Limit: count,
64
    ScanIndexForward: true, // Ascending by position (FIFO)
65
  })
66

67
  for (const entry of waiting.Items || []) {
68
    await admitUser(entry as QueueEntry)
69
  }
70
}
71

72
async function admitUser(entry: QueueEntry): Promise<void> {
73
  const token = generateCheckoutToken()
74
  const expiresAt = new Date(Date.now() + 5 * 60 * 1000) // 5 min
75

76
  await ddb.update({
77
    TableName: "FlashSaleQueue",
78
    Key: { sale_id: entry.sale_id, queue_ticket: entry.queue_ticket },
79
    UpdateExpression: "SET #status = :admitted, checkout_token = :token, token_expires_at = :exp",
80
    ExpressionAttributeNames: { "#status": "status" },
81
    ExpressionAttributeValues: {
82
      ":admitted": "admitted",
83
      ":token": token,
84
      ":exp": expiresAt.toISOString(),
85
    },
86
  })
87

88
  // Also store token in Redis for fast lookup during checkout
89
  await redis.setex(`token:${token}`, 300, entry.user_id)
90
}

11 collapsed lines
1
import Redis from "ioredis"
2
import { readFileSync } from "fs"
3

4
const redis = new Redis.Cluster([
5
  { host: "redis-1.example.com", port: 6379 },
6
  { host: "redis-2.example.com", port: 6379 },
7
  { host: "redis-3.example.com", port: 6379 },
8
])
9

10
const reserveScript = readFileSync("./reserve_inventory.lua", "utf-8")
11

12
interface ReservationResult {
13
  success: boolean
14
  reservation_id?: string
15
  remaining?: number
16
  error?: string
17
}
18

19
export async function reserveInventory(
20
  productId: string,
21
  userId: string,
22
  quantity: number,
23
  ttlSeconds: number = 300,
24
): Promise<ReservationResult> {
25
  const reservationId = `res_${Date.now()}_${userId}`
26

27
  const result = (await redis.eval(
28
    reserveScript,
29
    2, // number of keys
30
    `inventory:${productId}`,
31
    `reserved:${productId}`,
32
    userId,
33
    quantity.toString(),
34
    reservationId,
35
    ttlSeconds.toString(),
36
  )) as any
37

38
  if (result.err) {
39
    return { success: false, error: result.err }
40
  }
41

42
  return {
43
    success: true,
44
    reservation_id: reservationId,
45
    remaining: result.remaining,
46
  }
47
}
48

14 collapsed lines
49
export async function releaseReservation(productId: string, reservationId: string): Promise<void> {
50
  // Called when checkout times out or user abandons
51
  const reserved = await redis.hget(`reserved:${productId}`, reservationId)
52
  if (reserved) {
53
    const { quantity } = JSON.parse(reserved)
54
    await redis.incrby(`inventory:${productId}`, quantity)
55
    await redis.hdel(`reserved:${productId}`, reservationId)
56
  }
57
}
58

59
export async function confirmReservation(productId: string, reservationId: string): Promise<void> {
60
  // Called after successful payment - just remove from reserved set
61
  await redis.hdel(`reserved:${productId}`, reservationId)
62
}

9 collapsed lines
1
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs"
2
import { v4 as uuid } from "uuid"
3

4
const sqs = new SQSClient({})
5
const ORDER_QUEUE_URL = process.env.ORDER_QUEUE_URL!
6

7
interface OrderRequest {
8
  session_id: string
9
  user_id: string
10
  product_id: string
11
  quantity: number
12
  shipping_address: Address
13
  payment_method_id: string
14
}
15

16
export async function submitOrder(request: OrderRequest): Promise<{ order_id: string }> {
17
  const orderId = uuid()
18
  const idempotencyKey = `${request.user_id}:${request.session_id}`
19

20
  // Check for duplicate submission
21
  const existing = await db.orders.findOne({ idempotency_key: idempotencyKey })
22
  if (existing) {
23
    return { order_id: existing.id }
24
  }
25

26
  // Create order record in pending state
27
  await db.orders.insert({
28
    id: orderId,
29
    user_id: request.user_id,
30
    product_id: request.product_id,
31
    quantity: request.quantity,
32
    status: "pending",
33
    idempotency_key: idempotencyKey,
34
    created_at: new Date(),
35
  })
36

37
  // Queue for async processing
38
  await sqs.send(
39
    new SendMessageCommand({
40
      QueueUrl: ORDER_QUEUE_URL,
41
      MessageBody: JSON.stringify({
42
        order_id: orderId,
43
        ...request,
44
      }),
45
      MessageDeduplicationId: idempotencyKey,
46
      MessageGroupId: request.user_id, // Ensures per-user ordering
47
    }),
48
  )
49

50
  return { order_id: orderId }
51
}

14 collapsed lines
1
import { SQSEvent, SQSRecord } from "aws-lambda"
2
import Stripe from "stripe"
3

4
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
5

6
interface OrderMessage {
7
  order_id: string
8
  user_id: string
9
  product_id: string
10
  quantity: number
11
  shipping_address: Address
12
  payment_method_id: string
13
  session_id: string
14
}
15

16
export async function handler(event: SQSEvent): Promise<void> {
17
  for (const record of event.Records) {
18
    await processOrder(record)
19
  }
20
}
21

22
async function processOrder(record: SQSRecord): Promise<void> {
23
  const message: OrderMessage = JSON.parse(record.body)
24

25
  try {
26
    // 1. Verify reservation still valid
27
    const reservation = await getReservation(message.product_id, message.session_id)
28
    if (!reservation) {
29
      await markOrderFailed(message.order_id, "reservation_expired")
30
      return
31
    }
32

33
    // 2. Process payment
34
    const paymentIntent = await stripe.paymentIntents.create({
35
      amount: calculateTotal(message.product_id, message.quantity),
36
      currency: "usd",
37
      payment_method: message.payment_method_id,
38
      confirm: true,
39
      idempotency_key: `payment_${message.order_id}`,
40
    })
41

42
    if (paymentIntent.status !== "succeeded") {
43
      await releaseReservation(message.product_id, message.session_id)
44
      await markOrderFailed(message.order_id, "payment_failed")
45
      return
46
    }
47

48
    // 3. Confirm inventory (remove from reserved set)
49
    await confirmReservation(message.product_id, message.session_id)
50

51
    // 4. Update order status
52
    await db.orders.update(message.order_id, {
53
      status: "confirmed",
54
      payment_intent_id: paymentIntent.id,
55
      confirmed_at: new Date(),
56
    })
57

58
    // 5. Send confirmation
59
    await sendOrderConfirmation(message.order_id)
60
  } catch (error) {
61
    // Let SQS retry with exponential backoff
62
    throw error
63
  }
64
}
65

66
async function markOrderFailed(orderId: string, reason: string): Promise<void> {
67
  await db.orders.update(orderId, {
68
    status: "failed",
6 collapsed lines
69
    failure_reason: reason,
70
  })
71

72
  // Notify user
73
  await sendOrderFailureNotification(orderId, reason)
74
}

1
export async function handleDeadLetter(record: SQSRecord): Promise<void> {
2
  const message = JSON.parse(record.body)
3

4
  // Log for investigation
5
  console.error("Order failed permanently", {
6
    order_id: message.order_id,
7
    attempts: record.attributes.ApproximateReceiveCount,
8
    error: record.attributes.DeadLetterQueueSourceArn,
9
  })
10

11
  // Alert ops team
12
  await pagerduty.createIncident({
13
    title: `Flash sale order failed: ${message.order_id}`,
14
    severity: "high",
15
  })
16

17
  // Release inventory back to pool
18
  await releaseReservation(message.product_id, message.session_id)
19
}

4 collapsed lines
1
interface BotSignals {
2
  score: number
3
  signals: string[]
4
}
5

6
export function detectBot(request: Request): BotSignals {
7
  const signals: string[] = []
8
  let score = 0
9

10
  // Device fingerprint consistency
11
  const fp = request.headers.get("x-device-fingerprint")
12
  if (!fp || fp.length < 32) {
13
    signals.push("missing_fingerprint")
14
    score += 30
15
  }
16

17
  // Behavioral signals
18
  const timing = parseTimingHeader(request)
19
  if (timing.pageLoadToAction < 500) {
20
    // < 500ms is suspicious
21
    signals.push("fast_interaction")
22
    score += 25
23
  }
24

25
  // Browser consistency
26
  const ua = request.headers.get("user-agent")
27
  const acceptLang = request.headers.get("accept-language")
28
  if (isHeadlessBrowser(ua) || !acceptLang) {
29
    signals.push("headless_indicators")
30
    score += 40
31
  }
32

33
  // Known residential proxy detection
11 collapsed lines
34
  const ip = getClientIP(request)
35
  if (await isResidentialProxy(ip)) {
36
    signals.push("residential_proxy")
37
    score += 20
38
  }
39

40
  return { score, signals }
41
}
42

43
export function shouldChallenge(signals: BotSignals): boolean {
44
  return signals.score >= 50
45
}
46

47
export function shouldBlock(signals: BotSignals): boolean {
48
  return signals.score >= 80
49
}

1
export async function validateQueueJoin(
2
  userId: string,
3
  deviceFingerprint: string,
4
  saleId: string,
5
): Promise<{ allowed: boolean; reason?: string }> {
6
  // Check for duplicate user
7
  const existingEntry = await findUserInQueue(saleId, userId)
8
  if (existingEntry) {
9
    return { allowed: false, reason: "already_in_queue" }
10
  }
11

12
  // Check for fingerprint reuse (same device, different accounts)
13
  const fpCount = await countFingerprintInQueue(saleId, deviceFingerprint)
14
  if (fpCount >= 2) {
15
    return { allowed: false, reason: "device_limit_exceeded" }
16
  }
17

18
  // Velocity check: how many queues has this user joined recently?
19
  const recentJoins = await countRecentQueueJoins(userId, 3600) // last hour
20
  if (recentJoins >= 5) {
21
    return { allowed: false, reason: "velocity_exceeded" }
22
  }
23

24
  return { allowed: true }
25
}

1
async function submitOrder(orderData: OrderData): Promise<void> {
2
  // Optimistic: show "Processing..." immediately
3
  setOrderStatus("processing")
4
  showConfirmationPreview(orderData)
5

6
  try {
7
    const { order_id } = await api.submitOrder(orderData)
8

9
    // Poll for confirmation (async processing)
10
    pollOrderStatus(order_id, (status) => {
11
      if (status === "confirmed") {
12
        setOrderStatus("confirmed")
13
        showSuccessAnimation()
14
      } else if (status === "failed") {
15
        setOrderStatus("failed")
16
        showRetryOption()
17
      }
18
    })
19
  } catch (error) {
20
    // Revert optimistic UI
21
    setOrderStatus("error")
22
    showErrorMessage(error)
23
  }
24
}