Backend for Frontend — Cache Key Versioning Pitfalls

┌─────────────────────────────────────────────────────────┐
│                     CLIENT LAYER                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  iOS/Android │  │  React Web   │  │  Partner API  │  │
│  │  Mobile App  │  │  Dashboard   │  │  Consumer     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬────────┘  │
└─────────┼────────────────┼─────────────────┼────────────┘
          │                │                 │
          ▼                ▼                 ▼
┌─────────────────────────────────────────────────────────┐
│                   BFF LAYER                              │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐ │
│  │  Mobile BFF  │  │   Web BFF    │  │  Partner BFF  │ │
│  │  (Node.js)   │  │  (Node.js)   │  │  (Node.js)    │ │
│  │              │  │              │  │               │ │
│  │ - Compresses │  │ - Aggregates │  │ - Versioned   │ │
│  │   payloads   │  │   multi-svc  │  │   contracts   │ │
│  │ - Offline    │  │ - SSE/WS     │  │ - OAuth2      │ │
│  │   delta sync │  │   support    │  │   scoping     │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬────────┘ │
└─────────┼────────────────┼─────────────────┼───────────┘
          │                │                 │
          └────────────────┴─────────────────┘
                           │
          ┌────────────────▼────────────────┐
          │        INTERNAL SERVICE MESH     │
          │  ┌───────────┐  ┌────────────┐  │
          │  │  User Svc │  │ Order Svc  │  │
          │  └───────────┘  └────────────┘  │
          │  ┌───────────┐  ┌────────────┐  │
          │  │Product Svc│  │Inventory   │  │
          │  └───────────┘  │Svc         │  │
          │                 └────────────┘  │
          └─────────────────────────────────┘

KEY INSIGHT: Each BFF is owned by the frontend team that uses it.
The internal services have no knowledge of client-specific concerns.

// Mobile BFF — Home Screen Aggregation Endpoint
// Owned by: Mobile Platform Team
// Downstream deps: User Service, Order Service, Recommendation Service

import express from 'express';
import { verifyMobileJwt } from './auth/jwtValidator.js';
import { fetchUserProfile } from './clients/userServiceClient.js';
import { fetchRecentOrders } from './clients/orderServiceClient.js';
import { fetchRecommendations } from './clients/recommendationServiceClient.js';
import { projectFields } from './utils/fieldProjector.js';
import { buildErrorEnvelope } from './utils/errorNormaliser.js';

const router = express.Router();

// ─────────────────────────────────────────────────────────────
// FIELD PROJECTION MAPS
// These define EXACTLY what the mobile home screen renders.
// If a field isn't in this map, it never leaves the BFF.
// This is your first line of defence against over-fetching.
// ─────────────────────────────────────────────────────────────
const MOBILE_USER_FIELDS = ['userId', 'displayName', 'avatarUrl', 'loyaltyTier'];
const MOBILE_ORDER_FIELDS = ['orderId', 'status', 'estimatedDelivery', 'itemCount'];
const MOBILE_RECO_FIELDS  = ['productId', 'thumbnailUrl', 'title', 'priceFormatted'];

// ─────────────────────────────────────────────────────────────
// AUTH MIDDLEWARE
// Validates the mobile JWT. On success, attaches decoded payload
// to req.authenticatedUser so downstream handlers don't re-verify.
// The BFF then calls internal services with a SERVICE_ACCOUNT_TOKEN
// — the client never sees or needs internal credentials.
// ─────────────────────────────────────────────────────────────
router.use(verifyMobileJwt);

// ─────────────────────────────────────────────────────────────
// GET /mobile/v1/home
// Returns a single aggregated payload for the mobile home screen.
// Designed for: < 50KB response, < 500ms p95 on 4G.
// ─────────────────────────────────────────────────────────────
router.get('/v1/home', async (req, res) => {
  const { userId } = req.authenticatedUser; // populated by verifyMobileJwt middleware
  const requestStartTime = Date.now();

  // ── PARALLEL FAN-OUT ──────────────────────────────────────
  // We use Promise.allSettled instead of Promise.all.
  // Promise.all would FAIL ENTIRELY if recommendations are down.
  // Promise.allSettled lets us return partial data gracefully —
  // the home screen can still render without recommendations.
  const [userResult, ordersResult, recoResult] = await Promise.allSettled([
    fetchUserProfile(userId),
    fetchRecentOrders(userId, { limit: 3 }),        // mobile only shows 3
    fetchRecommendations(userId, { limit: 6 }),     // 2-column grid = 6 tiles
  ]);

  // ── CRITICAL DEPENDENCY CHECK ─────────────────────────────
  // User profile is non-negotiable. If it fails, the home screen
  // cannot render at all. Return a normalised 503 immediately.
  if (userResult.status === 'rejected') {
    const errorEnvelope = buildErrorEnvelope({
      code:    'USER_PROFILE_UNAVAILABLE',
      message: 'Could not load your profile. Please try again.',
      traceId: req.traceId,   // propagated from upstream via X-Trace-Id header
      retryable: true,
    });
    return res.status(503).json(errorEnvelope);
  }

  // ── NON-CRITICAL DEPENDENCY DEGRADATION ──────────────────
  // Orders or recommendations being unavailable degrades gracefully.
  // We log the failure for alerting but don't blow up the response.
  const recentOrders = ordersResult.status === 'fulfilled'
    ? projectFields(ordersResult.value.orders, MOBILE_ORDER_FIELDS)
    : [];  // empty array tells the UI to render the 'no recent orders' state

  const recommendations = recoResult.status === 'fulfilled'
    ? projectFields(recoResult.value.items, MOBILE_RECO_FIELDS)
    : [];  // UI renders a placeholder skeleton instead of crashing

  // ── LOG DEGRADED DEPENDENCIES ────────────────────────────
  // In production: emit a metric here (e.g. StatsD/Prometheus counter)
  // so your on-call team sees recommendation-service degradation
  // on the dashboard before users start complaining.
  if (ordersResult.status === 'rejected') {
    console.error('[MobileBFF] Order service degraded', {
      userId,
      reason: ordersResult.reason?.message,
      traceId: req.traceId,
    });
  }
  if (recoResult.status === 'rejected') {
    console.error('[MobileBFF] Recommendation service degraded', {
      userId,
      reason: recoResult.reason?.message,
      traceId: req.traceId,
    });
  }

  // ── RESPONSE PROJECTION ───────────────────────────────────
  // projectFields strips every key not in the MOBILE_*_FIELDS arrays.
  // The user service returns ~40 fields. We expose 4.
  // This is not just bandwidth — it prevents accidentally leaking
  // internal fields like 'fraudScore' or 'internalSegmentTag'.
  const projectedUser = projectFields(userResult.value, MOBILE_USER_FIELDS);

  // ── RESPONSE ENVELOPE ─────────────────────────────────────
  // Single, consistent response shape. The mobile app team defined
  // this contract — they own the BFF so they own the contract.
  const responsePayload = {
    meta: {
      traceId:       req.traceId,
      generatedAt:   new Date().toISOString(),
      latencyMs:     Date.now() - requestStartTime,
      degraded:      recentOrders.length === 0 || recommendations.length === 0,
    },
    user:            projectedUser,
    recentOrders,
    recommendations,
  };

  // ── CACHE HEADERS FOR CDN/MOBILE CACHE ───────────────────
  // Home screen data is user-specific — never publicly cacheable.
  // s-maxage=0 prevents CDN caching. max-age=30 allows the mobile
  // client to use stale data for 30 seconds on navigation back.
  res.set('Cache-Control', 'private, max-age=30, s-maxage=0');
  return res.status(200).json(responsePayload);
});

export default router;

// BFF Cache Layer — Redis-backed with stampede protection
// Uses probabilistic early recompute (PER) to avoid thundering herd.

import { createClient } from 'redis';

const redisClient = createClient({ url: process.env.REDIS_URL });
await redisClient.connect();

// ─────────────────────────────────────────────────────────────
// PROBABILISTIC EARLY RECOMPUTE (PER)
// Instead of letting every instance race to recompute an expired key,
// we start recomputing early with a probability that increases as
// the TTL approaches 0. Only one instance does the recompute.
// Formula from the academic paper by Vattani et al. (2015):
//   recompute_now = current_time - (recompute_cost * beta * ln(random()))
//                  > expiry_time
// ─────────────────────────────────────────────────────────────
const BETA = 1.0; // tuning parameter; 1.0 is a safe default

async function getOrRecompute({ cacheKey, ttlSeconds, recomputeMs, fetchFn }) {
  // Fetch the raw cached value AND its remaining TTL in one pipeline
  const pipeline = redisClient.multi();
  pipeline.get(cacheKey);
  pipeline.ttl(cacheKey); // returns remaining seconds, -2 if key doesn't exist
  const [cachedJson, remainingTtl] = await pipeline.exec();

  if (cachedJson) {
    const cachedValue = JSON.parse(cachedJson);

    // ── PER EARLY RECOMPUTE CHECK ───────────────────────────
    // Convert recompute cost to seconds for comparison with TTL
    const recomputeCostSeconds = recomputeMs / 1000;

    // Math.log returns a negative number for 0 < x < 1, so we negate it
    // This gives us a positive 'recompute window' proportional to cost
    const earlyRecomputeWindow = recomputeCostSeconds * BETA * -Math.log(Math.random());

    const shouldRecomputeEarly = remainingTtl < earlyRecomputeWindow;

    if (!shouldRecomputeEarly) {
      // Cache hit — return immediately without touching downstream services
      return { data: cachedValue, fromCache: true, remainingTtl };
    }
    // Falls through to recompute — probabilistic, so only some instances do this
  }

  // ── CACHE MISS OR EARLY RECOMPUTE ────────────────────────
  console.info(`[BFFCache] Recomputing: ${cacheKey}`);
  const freshData = await fetchFn(); // calls the actual aggregation logic

  // Store with a jittered TTL to prevent synchronised mass expiration.
  // Without jitter: all 100k user caches expire at :00 every minute.
  // With jitter: expiry is spread across 45–75 seconds.
  const jitterSeconds = Math.floor(Math.random() * 30) - 15; // ±15s
  const effectiveTtl  = ttlSeconds + jitterSeconds;

  await redisClient.set(cacheKey, JSON.stringify(freshData), {
    EX: effectiveTtl, // sets TTL in seconds
  });

  return { data: freshData, fromCache: false, remainingTtl: effectiveTtl };
}

// ─────────────────────────────────────────────────────────────
// FIELD PROJECTOR
// Strips all keys not in the allowedFields array.
// Works on both single objects and arrays of objects.
// This is a whitelist approach — safer than a blacklist.
// ─────────────────────────────────────────────────────────────
export function projectFields(input, allowedFields) {
  if (Array.isArray(input)) {
    return input.map(item => projectFields(item, allowedFields));
  }
  // Object.fromEntries + filter = clean, readable field projection
  return Object.fromEntries(
    Object.entries(input).filter(([key]) => allowedFields.includes(key))
  );
}

// ─────────────────────────────────────────────────────────────
// USAGE EXAMPLE — How the home screen route uses the cache layer
// ─────────────────────────────────────────────────────────────
export async function getCachedHomeScreenData(userId, aggregateFn) {
  const cacheKey = `mobile:homescreen:v2:${userId}`; // versioned key!
  // If you change the response shape, bump v2 → v3 to avoid stale
  // shape mismatches. Unversioned cache keys are a production horror.

  return getOrRecompute({
    cacheKey,
    ttlSeconds:   60,   // 60s base TTL, ±15s jitter applied inside
    recomputeMs:  250,  // estimated cost of the aggregation fan-out
    fetchFn:      () => aggregateFn(userId),
  });
}

DECISION FLOWCHART: API Gateway vs BFF vs GraphQL

START
  │
  ├─ Do ALL your clients need the same data shape?
  │    └─ YES → API Gateway with response caching is probably enough.
  │             BFF adds cost without benefit here.
  │
  ├─ Do you have ONE flexible client (web SPA) that knows
  │  what fields it needs at query time?
  │    └─ YES → GraphQL BFF may be the right call.
  │             But plan for DataLoader from day one or
  │             you'll have N+1 queries in production within a week.
  │
  ├─ Do you have MULTIPLE distinct client surfaces
  │  (mobile, web, third-party) with different teams?
  │    └─ YES → BFF per client surface.
  │             Each team owns their BFF.
  │             Deploy independently. Schema evolves independently.
  │
  └─ Are you a startup with 2 engineers and 1 client?
       └─ YES → Monolith or single lightweight API.
               BFF is premature abstraction at this scale.
               Add it when the second client surface arrives.

─────────────────────────────────────────────────────────────
ORGANISATIONAL OWNERSHIP MAPPING
─────────────────────────────────────────────────────────────

  API Gateway     →  Platform/Infra Team owns it
                     (shared, slow to change)

  BFF (Mobile)    →  Mobile Team owns it
                     (fast iteration, team autonomy)

  BFF (Web)       →  Web Frontend Team owns it
                     (fast iteration, team autonomy)

  Core Services   →  Domain Teams own them
                     (stable APIs, domain logic only)

─────────────────────────────────────────────────────────────
PERFORMANCE CHARACTERISTICS UNDER LOAD
─────────────────────────────────────────────────────────────

  Single API Gateway (aggregation pushed into gateway):
  - One bottleneck for all clients
  - Any client's traffic pattern affects all others
  - Horizontal scaling scales for everyone, wastefully

  Dedicated BFF per client:
  - Mobile BFF scales independently of web traffic spikes
  - Web BFF can use larger instances (web pays for richer data)
  - Mobile BFF can use smaller, cheaper instances (smaller payloads)
  - Failure in web BFF doesn't affect mobile availability

// io.thecodeforge — system-design tutorial

class ClientProfile:
    def __init__(self, client_type: str):
        self.type = client_type
        self.data_shape = self._get_shape()
    
    def _get_shape(self) -> dict:
        # If both clients return the same shape, you don't need a BFF
        profiles = {
            "web": {"user_id", "name", "email", "full_history"},
            "mobile": {"user_id", "name", "email", "recent_summary"},
            "iot": {"device_id", "status", "last_seen"}
        }
        return profiles.get(self.type, {})

web = ClientProfile("web")
mobile = ClientProfile("mobile")
print(f"Shared fields: {web.data_shape & mobile.data_shape}")
print(f"Unique to web: {web.data_shape - mobile.data_shape}")
print(f"Unique to mobile: {mobile.data_shape - mobile.data_shape}")

// io.thecodeforge — system-design tutorial

def spotify_mobile_bff(user_id: str, region: str):
    # BFF: mobile needs lightweight, cached data with connectivity resilience
    tracks = fetch_tracks_from_cache(user_id, region)
    if not tracks:
        tracks = music_service.get_tracks(user_id, limit=10)
        set_cache(region, tracks, ttl=300)
    return compress_protobuf({
        "track_snippets": [t.preview_url for t in tracks],
        "offline_available": all(t.cached_locally for t in tracks)
    })

def spotify_desktop_bff(user_id: str):
    # BFF: desktop wants full entities, no compression
    tracks = music_service.get_tracks(user_id, limit=50)
    return {
        "tracks": [{
            "id": t.id,
            "name": t.name,
            "artists": t.artists,
            "album_art_url": t.album_art_4k
        } for t in tracks],
        "collaborative_playlists": playlist_service.get_shared(user_id)
    }

// io.thecodeforge — system-design tutorial

import falcon

class DeviceRouter:
    def __init__(self):
        self.bffs = {
            "TV": TVBFF(),
            "MOBILE": MobileBFF(),
            "WEB": WebBFF()
        }
    
    def on_get(self, req, resp):
        device = req.headers.get("X-Device-Type", "WEB")
        bff = self.bffs.get(device, self.bffs["WEB"])
        payload = bff.serve(req)
        resp.media = payload

class TVBFF:
    def serve(self, req):
        # Batch all data—TV has high bandwidth, low latency tolerance
        return {"recommendations": [...], "trailers": [...], "ui_metadata": {...}}

app = falcon.App()
app.add_route("/", DeviceRouter())

// io.thecodeforge — system-design tutorial

import asyncio

async def checkout_bff(session_id):
    async def fetch_inventory():
        return {"in_stock": True, "eta_days": 2}
    
    async def fetch_pricing():
        return {"subtotal": 29.99, "tax": 2.40}
    
    async def fetch_shipping():
        return {"cost": 0.0, "method": "prime"}
    
    inventory, pricing, shipping = await asyncio.gather(
        fetch_inventory(),
        fetch_pricing(),
        fetch_shipping()
    )
    
    return {
        "button": {
            "enabled": True,
            "total": pricing["subtotal"] + pricing["tax"] + shipping["cost"],
            "eta": inventory["eta_days"],
            "shipping_method": shipping["method"]
        }
    }

# Invoke
result = await checkout_bff("abc123")
print(result)

// io.thecodeforge — system-design tutorial

import asyncio

class AirbnbMobileBFF:
    async def get_listing(self, listing_id: str):
        pricing, reviews, details = await asyncio.gather(
            self._fetch_pricing(listing_id),
            self._fetch_reviews(listing_id, limit=3),
            self._fetch_details(listing_id)
        )
        return self._compress_photos(details) | {"price": pricing, "top_reviews": reviews}

    async def _fetch_pricing(self, id): ...
    async def _fetch_reviews(self, id, limit): ...
    async def _fetch_details(self, id): ...
    def _compress_photos(self, d): return {k: v for k, v in d.items() if k != 'full_res_photos'}

// io.thecodeforge — system-design tutorial

import time

def bff_request():
    start = time.time()
    # 1 call: aggregated response
    data = {"user": {"name": "Alice"}, "orders": [
        {"id": 1, "total": 50}]}
    return time.time() - start  # ~5ms

def graphql_request():
    start = time.time()
    # 4 resolver calls: user, orders, items, shipping
    _ = {"user": {"name": "Alice"}}
    _ = {"orders": [{"id": 1}]}
    _ = {"items": [{"sku": "X"}]}
    _ = {"shipping": {"status": "delivered"}}
    return time.time() - start  # ~25ms

print(f"BFF: {bff_request()*1000:.1f}ms  GraphQL: {graphql_request()*1000:.1f}ms")

// io.thecodeforge — system-design tutorial

STANDALONE = {
    "latency_overhead_ms": 2,
    "scaling": "per bff type",
    "team isolation": True,
    "resource_cost": "medium"
}
SIDECAR = {
    "latency_overhead_ms": 0.1,
    "scaling": "per pod",
    "team isolation": False,
    "resource_cost": "high"
}
INGRESS_MESH = {
    "latency_overhead_ms": 0.5,
    "scaling": "cluster wide",
    "team isolation": False,
    "maintainability": "low"
}
for model, props in [("Standalone", STANDALONE), (
    "Sidecar", SIDECAR), ("Ingress Mesh", INGRESS_MESH)]:
    print(f"{model}: +{props['latency_overhead_ms']}ms, {props['team_isolation']}")

// io.thecodeforge — system-design tutorial
import asyncio

class Observer:
    def update(self, event):
        raise NotImplementedError

class MobileBFF:
    def __init__(self):
        self._observers = {}

    def attach(self, client_id, observer):
        self._observers[client_id] = observer
        return self

    def detach(self, client_id):
        self._observers.pop(client_id, None)

    async def notify(self, event):
        for obs in self._observers.values():
            await obs.update(event)

class StockObserver(Observer):
    async def update(self, event):
        print(f"Push price ${event['price']} to client")