Scalability Concepts Explained — Vertical, Horizontal and Beyond

// ─────────────────────────────────────────────────────────────
// SCALING DECISION FRAMEWORK
// Run this mental checklist BEFORE choosing a scaling strategy
// ─────────────────────────────────────────────────────────────

function chooseScalingStrategy(currentLoad, projectedLoad, appIsStateless):

    // Step 1: Calculate how much headroom you need
    growthFactor = projectedLoad / currentLoad
    // e.g. Black Friday estimate: 50,000 rps / 500 rps = 100x growth needed

    // Step 2: Check if vertical scaling can close the gap cheaply
    currentInstanceType  = "db.t3.medium"   // 2 vCPU, 4 GB RAM
    upgradedInstanceType = "db.r6g.4xlarge" // 16 vCPU, 128 GB RAM  (~8x capacity)

    if growthFactor <= 8 AND upgradedInstanceType IS available:
        // Vertical scaling is simpler and fast — do it first
        return SCALE_UP(
            targetInstance = upgradedInstanceType,
            estimatedCost  = "$0.90/hr → $4.80/hr",  // predictable pricing
            operationalRisk = LOW                      // no code changes needed
        )

    // Step 3: Beyond vertical ceiling — must go horizontal
    if growthFactor > 8 OR upgradedInstanceType NOT available:

        if NOT appIsStateless:
            // ⚠️  STOP — horizontal scaling WILL BREAK stateful apps
            // Sessions stored in-memory on Server A won't exist on Server B
            return REFACTOR_FIRST(
                action = "Move sessions to Redis / JWT tokens",
                reason = "Load balancer will route user requests to ANY server"
            )

        // App is stateless — safe to scale out
        return SCALE_OUT(
            addNodes        = ceil(growthFactor / capacityPerNode),
            loadBalancer    = "Round-robin or least-connections",
            operationalRisk = MEDIUM  // distributed systems add failure modes
        )

// ─── EXAMPLE OUTPUT ──────────────────────────────────────────
// Input:  currentLoad=500rps, projectedLoad=50000rps, stateless=false
// Output: REFACTOR_FIRST
//         → Move sessions to Redis THEN scale horizontally
//
// Input:  currentLoad=500rps, projectedLoad=2000rps, stateless=true
// Output: SCALE_UP
//         → Upgrade instance (4x growth, within vertical ceiling)
// ─────────────────────────────────────────────────────────────

// ─────────────────────────────────────────────────────────────
// STATELESS REQUEST FLOW WITH LOAD BALANCER
// Demonstrates how a stateless API handles auth across two servers
// ─────────────────────────────────────────────────────────────

// ── SHARED INFRASTRUCTURE (lives outside any single server) ──
redisSessionStore = ExternalRedis(host="redis.internal", port=6379)
jwtSecretKey      = EnvironmentVariable("JWT_SECRET")  // same key on ALL servers

// ── SERVER A and SERVER B are identical clones ────────────────
function handleRequest(incomingHttpRequest):

    // Load balancer already decided this request lands here
    // We don't know or care which server handled the previous request

    authHeader = incomingHttpRequest.headers["Authorization"]
    // e.g. "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

    if authHeader is null:
        return HTTP_401("Missing auth token")

    jwtToken = authHeader.stripPrefix("Bearer ")

    // Verify the JWT using the shared secret — works on ANY server
    // because the secret is the same everywhere and state is IN the token
    decodedPayload = JWT.verify(jwtToken, jwtSecretKey)
    // decodedPayload = { userId: "usr_8821", role: "admin", exp: 1712000000 }

    if decodedPayload.isExpired():
        return HTTP_401("Token expired — please log in again")

    // Fetch user-specific data from the SHARED store (not local memory)
    userCart = redisSessionStore.get(key = "cart:" + decodedPayload.userId)
    // userCart = [{ productId: "prod_44", qty: 2 }, { productId: "prod_91", qty: 1 }]

    // Process the request normally
    orderTotal = calculateTotal(userCart)

    return HTTP_200({ cart: userCart, total: orderTotal })

// ── WHAT MAKES THIS STATELESS ─────────────────────────────────
// 1. No in-memory session map — server restarts lose NOTHING
// 2. JWT carries identity — valid on Server A, B, or C equally
// 3. Cart lives in Redis — Server B reads the same cart as Server A
// 4. Load balancer can route usr_8821's next request ANYWHERE safely

// ── LOAD BALANCER LOGIC (simplified) ─────────────────────────
serverPool = [ServerA(weight=1), ServerB(weight=1), ServerC(weight=1)]

function routeIncomingRequest(request):
    // Least-connections strategy — helps when cart checkout is slow
    targetServer = serverPool.minBy(server => server.activeConnections)
    targetServer.activeConnections += 1

    response = targetServer.handleRequest(request)

    targetServer.activeConnections -= 1
    return response

// ─────────────────────────────────────────────────────────────
// CACHE-ASIDE PATTERN (also called Lazy Loading)
// The most common and safest caching strategy for web APIs
// Application controls what gets cached and when
// ─────────────────────────────────────────────────────────────

redisCache    = RedisClient(host="cache.internal")
primaryDB     = PostgresClient(host="db-primary.internal")
readReplicaDB = PostgresClient(host="db-replica.internal")  // read-only copy

// ── CACHE TTL STRATEGY ────────────────────────────────────────
// TTL (Time To Live) = how long cached data stays valid
// Too short → cache provides little benefit, DB still hammered
// Too long  → users see stale data after updates
PRODUCT_CATALOG_TTL = 300   // 5 minutes — changes rarely
USER_PROFILE_TTL    = 60    // 1 minute  — changes occasionally
LIVE_STOCK_COUNT_TTL = 5    // 5 seconds — must be near-realtime

function getProductCatalog(categoryId):
    cacheKey = "catalog:category:" + categoryId
    // e.g. "catalog:category:electronics"

    // ── STEP 1: Check the cache first (fast path) ─────────────
    cachedResult = redisCache.get(cacheKey)

    if cachedResult is NOT null:
        // Cache HIT — served in <1ms, database not touched
        logMetric("cache_hit", key=cacheKey)
        return JSON.parse(cachedResult)

    // ── STEP 2: Cache MISS — go to read replica ───────────────
    // Using read replica, not primary — keeps primary free for writes
    logMetric("cache_miss", key=cacheKey)

    freshProducts = readReplicaDB.query("""
        SELECT p.id, p.name, p.price, p.stock_count, c.name AS category
        FROM   products p
        JOIN   categories c ON c.id = p.category_id
        WHERE  p.category_id = :categoryId
          AND  p.is_active = true
        ORDER  BY p.created_at DESC
        LIMIT  50
    """, params={ categoryId: categoryId })
    // This query takes ~180ms on a warm database

    // ── STEP 3: Populate cache for next request ───────────────
    redisCache.setWithExpiry(
        key     = cacheKey,
        value   = JSON.stringify(freshProducts),
        ttlSecs = PRODUCT_CATALOG_TTL
    )

    return freshProducts

// ── CACHE INVALIDATION ON UPDATE ─────────────────────────────
// When a product changes, the cache for its category MUST be cleared
function updateProductPrice(productId, newPrice, categoryId):

    // Write always goes to PRIMARY database
    primaryDB.execute("""
        UPDATE products SET price = :newPrice, updated_at = NOW()
        WHERE  id = :productId
    """, params={ productId, newPrice })

    // Invalidate the cached category so next read gets fresh data
    staleCacheKey = "catalog:category:" + categoryId
    redisCache.delete(staleCacheKey)
    // Next call to getProductCatalog() will be a cache miss → DB fetch → repopulate

    logEvent("price_updated", productId=productId, cacheInvalidated=staleCacheKey)