03. Zero-Oversell Bounded Flash Sale EngineCopy Anchor Link

Production Paradigm: Atomic Distributed Lua Stock Reservation + Token Bucket Gateway Guard + Write-Behind Transactional Outbox + Automatic Compensation Rollback.

💥 The Real-World BottleneckCopy Anchor Link

In high-stakes flash sale campaigns (e.g., Black Friday 100 units of iPhone at 90% discount, or limited concert tickets), 50,000 users click "Buy Now" at the exact same millisecond.

A standard relational transaction triggers severe disasters:

-- The Oversell Disaster
BEGIN;
SELECT stock FROM items WHERE id = 101; -- 50,000 transactions read stock = 100
-- All 50,000 proceed to deduct:
UPDATE items SET stock = stock - 1 WHERE id = 101;
COMMIT;
-- Final Result: Stock is -49,900. The business loses millions.

If we use SELECT ... FOR UPDATE, the database experiences extreme lock contention, deadlocks, and connection pool starvation, dropping the entire application offline.

🏛️ High-Concurrency ArchitectureCopy Anchor Link

This blueprint achieves zero negative inventory and sub-2ms response latency by delegating the critical concurrency boundary to an atomic Lua script inside Valkey / Redis, coupled with an asynchronous transactional outbox.

Key Architectural PhasesCopy Anchor Link

1. Gateway Token Bucket Limiting:
   • Drops malicious bot floods and script attacks before they touch internal infrastructure.
2. Atomic Lua Stock Reservation (RESERVE_STOCK_LUA):
   • Executes single-threaded in Redis memory in < 1ms.
   • Checks available stock and decrements atomically. If stock is insufficient, it fails immediately with zero side-effects.
   • Sets a temporary reservation lease (e.g. 15 minutes) with user ID tagging to prevent duplicate claims.
3. Transactional Outbox with UUIDv7:
   • Decouples user checkout confirmation from heavy relational database writes.
   • Guaranteed at-least-once delivery with idempotent order processing.
4. Compensation Rollback (ROLLBACK_STOCK_LUA):
   • If user payment fails or expires, the reserved stock returns to the pool atomically.

🧩 Composed Functional SlicesCopy Anchor Link

💻 Code ImplementationCopy Anchor Link

mkdir -p src/lib/flash-sale
cp -r packages/resilient-cache/src/flashsale-engine src/lib/flash-sale/
cp -r packages/resilient-cache/src/rate-limiter src/lib/flash-sale/

import { FlashSaleEngine } from '@/lib/flash-sale/flashsale-engine';
import { TokenBucketLimiter } from '@/lib/flash-sale/rate-limiter';
import { redisClient } from '@/lib/redis';
import { db } from '@/lib/db';

const flashSale = new FlashSaleEngine({
  redis: redisClient,
  leaseTtlSeconds: 900, // 15-minute payment window
});

const rateLimiter = new TokenBucketLimiter({
  capacity: 50,
  refillRate: 10,
});

export async function purchaseFlashSaleItem(userId: string, skuId: string, qty: number = 1) {
  // 1. Gateway bot protection
  const isAllowed = await rateLimiter.consume(`rate:${userId}`);
  if (!isAllowed) throw new Error('Too many requests. Please slow down.');

  // 2. Atomic Lua stock reservation (<2ms)
  const reservation = await flashSale.reserveStock({
    skuId,
    userId,
    quantity: qty,
  });

  if (!reservation.success) {
    return { success: false, reason: 'SOLD_OUT' };
  }

  // 3. Queue asynchronous DB settlement via Outbox
  await db.outboxOrder.create({
    data: {
      reservationToken: reservation.token,
      skuId,
      userId,
      quantity: qty,
      status: 'PENDING_PAYMENT',
    },
  });

  return {
    success: true,
    reservationToken: reservation.token,
    expiresAt: reservation.expiresAt,
  };
}

📊 Production Scale Benchmark & VerificationCopy Anchor Link