E-Commerce API: 10K RPS, Sub-100ms p99

System Architecture

Stateless API layer behind a load balancer, with MongoDB for primary data and Redis for caching/sessions. Horizontal scaling via container orchestration. Database reads routed to replica set secondaries for read-heavy endpoints (product listings).

High-level components

• API Gateway / Load Balancer: AWS ALB distributing across ECS Fargate tasks
• Application Layer: 3+ Node.js/Express containers (stateless, horizontal scaling)
• Primary Database: MongoDB 3-node replica set (1 primary, 2 secondaries)
• Cache/Session Store: Redis Cluster (ElastiCache) for JWT blacklisting, rate limiting, product catalog caching
• Message Queue: SQS for async order confirmation emails, inventory webhooks

Request flow (simplified)

1. Client → ALB → Express app
2. Auth middleware validates JWT (Redis check for revocation)
3. Route handler executes business logic
4. Reads: MongoDB secondary (eventually consistent) | Writes: MongoDB primary
5. Response → Client (with caching headers where appropriate)

Authentication & Authorization

Stateless JWT with short-lived access tokens (15 min) and refresh tokens (7 days) stored in HttpOnly cookies. Token revocation via Redis blacklist for immediate logout/security events.

Implementation details

• Access Token: RS256 signed, 15-min expiry, contains user ID, roles, permissions
• Refresh Token: Opaque token stored in Redis with 7-day TTL, rotated on each use
• Password Hashing: Argon2id (memory-hard, resistant to GPU attacks)
• Rate Limiting: 10 req/min on auth endpoints, 100 req/min general (Redis sliding window)
• Security Headers: Helmet.js for CSP, HSTS, X-Frame-Options, Referrer-Policy

Why not sessions?

JWT enables stateless horizontal scaling — no sticky sessions, no shared session store latency. Refresh token rotation mitigates token theft risk.

Product Catalog & Variants

Flexible document model in MongoDB supporting unlimited product variants (size, color, material) without schema migrations. Embedded variants for read performance; separate collection for category/facet indexing.

Data model highlights

// Product document (simplified)
{
  _id: ObjectId,
  slug: "organic-cotton-tee",
  name: "Organic Cotton T-Shirt",
  basePrice: 29.99,
  currency: "USD",
  variants: [
    { sku: "OCT-S-BLK", attrs: { size: "S", color: "Black" }, stock: 42, priceDelta: 0 },
    { sku: "OCT-M-BLU", attrs: { size: "M", color: "Blue" }, stock: 18, priceDelta: 2.00 }
  ],
  categories: ["apparel", "organic", "t-shirts"],
  searchableText: "organic cotton t-shirt black blue small medium...", // for text index
  createdAt, updatedAt
}

Query patterns optimized

• List with filters: Compound index on {categories: 1, "variants.attrs.size": 1, "variants.attrs.color": 1, basePrice: 1}
• Search: Text index on searchableText with weights
• Single product: Direct _id or slug lookup (cached in Redis 1hr)

Checkout & Idempotent Order Processing

Idempotency keys on every mutating endpoint prevent duplicate orders from network retries. Client generates UUID v4 per checkout attempt; server stores key + response for 24 hours.

Order flow

1. Client POST /orders with Idempotency-Key header
2. Server checks Redis for existing key → returns cached response if found
3. Validate cart, reserve inventory (atomic findOneAndUpdate with $inc on variant stock)
4. Create order document with PENDING status
5. Publish OrderCreated event to SQS (payment, email, inventory webhook)
6. Return order ID + idempotency key to client

Why idempotency matters

Mobile networks, browser retries, and payment provider timeouts cause duplicate requests. Without idempotency: double charges, duplicate fulfillment, inventory corruption. With it: exactly-once semantics at application level.

Real-time Inventory with Aggregation Pipelines

MongoDB aggregation pipelines compute available stock in real-time across variants, reservations, and pending orders. No separate inventory service needed; single source of truth in MongoDB.

Available stock calculation (simplified)

db.products.aggregate([
  { $match: { _id: productId } },
  { $unwind: "$variants" },
  { $lookup: {
      from: "orders",
      localField: "variants.sku",
      foreignField: "items.sku",
      pipeline: [
        { $match: { status: { $in: ["PENDING", "CONFIRMED", "PROCESSING"] } } },
        { $group: { _id: "$items.sku", reserved: { $sum: "$items.qty" } } }
      ],
      as: "reservations"
  }},
  { $addFields: {
      available: { $subtract: ["$variants.stock", { $ifNull: [{ $sum: "$reservations.reserved" }, 0] }] }
  }},
  { $project: { sku: "$variants.sku", available: 1, attrs: "$variants.attrs" } }
])

Cached in Redis for 30 seconds on product detail pages. Cache invalidated on order creation via pub/sub.

Performance Metrics & Optimization

Load test results (k6, 5-min sustained): 10,200 RPS, p50=28ms, p95=67ms, p99=94ms, error rate <0.01%. Cost: ~$180/month on AWS (3x Fargate, MongoDB Atlas M30, ElastiCache cache.t3.micro).

Key optimizations

• Connection pooling: MongoDB driver pool (min 10, max 100), Redis cluster client
• Query projection: Only fetch required fields (e.g., list view excludes descriptions)
• Redis caching: Product details (1hr), category trees (24hr), user sessions
• Compression: Brotli via ALB, response payloads <10KB typical
• Indexes: Compound indexes matching query patterns; regular explain() reviews

Key Architecture Decisions (ADRs)

Lessons Learned

• Start with idempotency: Retrofitting idempotency keys is painful. Design it in from day one for any mutating endpoint.
• Monitor p99, not average: Average latency hides tail latency spikes that degrade UX. Alert on p99 > 200ms.
• Cache invalidation is hard: Use short TTLs (30-60s) for critical data; accept eventual consistency for non-critical.
• MongoDB aggregations are powerful: Replaced a separate inventory service with a single pipeline. Less code, fewer failure points.
• Load test early: Found connection pool exhaustion at 3K RPS before production. Fixed by tuning pool sizes and ALB idle timeout.