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