@wazir-dev/cli 1.0.0

package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md

@@ -0,0 +1,670 @@
+# Mobile Backend for Frontend (BFF) — Architecture Expertise Module
+
+> The Backend for Frontend pattern creates a dedicated backend service per client type (mobile, web, third-party) that aggregates, transforms, and optimizes API calls for that specific client's needs. This eliminates over-fetching, reduces mobile network calls, and gives frontend teams ownership of their API layer.
+
+> **Category:** Mobile Architecture
+> **Complexity:** Moderate
+> **Applies when:** Multiple client types (mobile, web, desktop) consuming the same backend services but needing different data shapes, aggregations, or response sizes
+
+---
+
+## What This Is (and What It Isn't)
+
+### The Core Idea
+
+The Backend for Frontend (BFF) pattern places a dedicated server-side component between a specific frontend application and the downstream backend services (microservices, databases, third-party APIs). Each client type — mobile, web, smart TV, third-party partner — gets its own BFF. The BFF aggregates calls to multiple backend services, reshapes the response to exactly what that frontend needs, and handles client-specific concerns like authentication token formats, caching headers, and payload compression.
+
+The term was coined by Phil Calcado at SoundCloud in 2015 and popularized by Sam Newman in his work on microservices patterns. The pattern emerged from a real engineering problem: SoundCloud's monolithic API was serving web clients, iOS, Android, and partner integrations through a single endpoint. Every change to satisfy one client's needs risked breaking another. The BFF pattern resolved this by giving each client type its own backend facade.
+
+### How It Works at a Structural Level
+
+```
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  iOS App     │  │  Android App │  │  Web SPA     │
+└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
+       │                 │                 │
+       ▼                 ▼                 ▼
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│  Mobile BFF  │  │  Mobile BFF  │  │   Web BFF    │
+│  (shared)    │  │  (shared)    │  │              │
+└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
+       │                 │                 │
+       └────────┬────────┘─────────┬───────┘
+                │                  │
+       ┌────────▼──────┐  ┌───────▼────────┐
+       │  User Service  │  │ Product Service │  ...N services
+       └───────────────┘  └────────────────┘
+```
+
+The mobile BFF receives a single request from the app, fans out to however many backend services are needed, assembles the response into the exact shape the mobile screen requires, and returns it. The mobile app makes one network call instead of five. The web BFF does the same thing but returns a richer payload suited to desktop rendering, perhaps including additional metadata that a mobile screen would never display.
+
+### What a BFF Is NOT
+
+**Not an API Gateway.** An API gateway is a single entry point for all clients. It handles cross-cutting concerns — rate limiting, authentication verification, TLS termination, request routing — but it does not contain client-specific business logic or response shaping. A BFF contains client-specific aggregation logic and is owned by the frontend team, not the platform team. In practice, many architectures use both: the API gateway handles infrastructure concerns, and BFFs sit behind it handling client-specific orchestration.
+
+**Not GraphQL (though GraphQL can implement a BFF).** GraphQL is a query language that lets clients request exactly the data they need. This solves over-fetching at the query level. A BFF solves it at the service level — aggregating multiple backend calls, handling error scenarios, implementing caching strategies, and performing server-side transformations. GraphQL can serve as the interface layer of a BFF, but a BFF without GraphQL (using REST) is perfectly valid, and GraphQL without a BFF (directly querying microservices) is a different architecture entirely.
+
+**Not a proxy.** A proxy forwards requests unchanged. A BFF transforms, aggregates, and optimizes. If your "BFF" just passes requests through to a single backend service, you do not have a BFF — you have a proxy adding latency.
+
+**Not a general-purpose backend.** The moment a BFF starts serving multiple unrelated client types, it stops being a BFF and becomes a general-purpose API. This is the most common way the pattern degrades.
+
+---
+
+## When to Use It
+
+### The Qualifying Conditions
+
+Apply the BFF pattern when **two or more** of these conditions hold:
+
+**Multiple client types with divergent needs.** You have a mobile app that needs compact payloads (100KB responses, not 2MB), a web app that needs rich data structures with embedded metadata, and perhaps a TV app that needs a completely different content hierarchy. A single API cannot serve all three well without becoming bloated with conditional logic, optional fields, and client-sniffing heuristics.
+
+**Mobile network constraints demand payload optimization.** Mobile devices operate on unreliable networks with high latency and limited bandwidth. Every unnecessary field in an API response costs battery and time. A BFF strips responses to exactly what the mobile screen needs. Netflix's mobile BFF, for example, returns artwork URLs sized for mobile screens, not the full resolution variants that the TV app requires.
+
+**Multiple backend services must be aggregated per screen.** A single mobile screen — say, a product detail page — needs data from the product service, the pricing service, the inventory service, the reviews service, and the recommendations service. Without a BFF, the mobile app makes five sequential or parallel HTTP calls over cellular, each with its own latency, error handling, and retry logic. With a BFF, one call to the server handles all five fan-outs over the fast datacenter network.
+
+**Frontend teams need API autonomy.** When the mobile team must file tickets with the backend team for every API change, velocity drops. A BFF owned by the mobile team lets them shape their API contract independently. They add fields, remove fields, and adjust response structures without coordinating across team boundaries.
+
+**Backend service contracts are unstable or evolving.** When downstream microservices are being refactored, versioned, or replaced, a BFF acts as an anti-corruption layer. The mobile app's contract with the BFF stays stable while the BFF adapts to changing backend contracts internally.
+
+### Real-World Contexts Where This Pays Off
+
+**Netflix** completed a year-long project rearchitecting their Android backend from a centralized API model to a dedicated BFF. The Android team took ownership of their backend service, enabling them to iterate on the API independently. Their BFF uses the Falcor data model and query protocol, allowing the app to query a list of paths in each HTTP request and receive specially formatted JSON (jsonGraph) used for client-side caching and UI hydration. The BFF aggregates data from separate backend microservices — the artwork service, video metadata service, personalization service — into a single response shaped for the Android rendering pipeline. Each platform (Android, iOS, smart TV, web) has its own BFF with its own optimization profile.
+
+**SoundCloud** pioneered the BFF pattern in 2013 when their monolithic API could no longer serve the divergent needs of their web player, iOS app, Android app, and partner integrations. They created one BFF per client type, allowing each team to optimize for its platform's constraints. The iOS and Android listener apps shared a single "mobile listener BFF" since their data needs were similar, while the web player and the creator tools each had their own BFFs. This approach let SoundCloud scale from one development team to multiple autonomous teams without API coordination bottlenecks.
+
+**Spotify** uses BFFs to serve different data shapes across their web player, mobile apps, desktop client, and smart speaker integrations. The mobile BFF delivers compact payloads optimized for streaming metadata and offline sync, while the desktop BFF delivers richer payloads suitable for the full desktop experience. Each client type's BFF is tuned for its specific performance characteristics.
+
+**Uber** employs BFFs to separate the rider app's backend from the driver app's backend. Each BFF handles ride requests, driver matching, and real-time tracking differently — the rider BFF focuses on estimated arrival and pricing, while the driver BFF focuses on navigation, earnings, and ride queue management. This separation allows each app's backend to evolve independently even though they share underlying microservices.
+
+**IKEA** adopted a vertical-slice architecture with BFF characteristics when they replaced their monolithic IKEA Retail Web (IRW) system with a microfrontends architecture. Each product team owns a vertical slice including its own backend-for-frontend layer. The platform now serves 48 countries with 50+ product teams, handling billions of sessions annually. The BFF approach enables each team to optimize its slice independently without cross-team API coordination.
+
+---
+
+## When NOT to Use It
+
+This section is intentionally long because the BFF pattern is frequently applied where it adds cost without proportional benefit.
+
+### Disqualifying Conditions
+
+**Single client type.** If you only have one frontend — a web app, or a single mobile app — there is no "frontend divergence" to solve. A well-designed API serving one client does not benefit from an intermediary BFF layer. You are adding a network hop, a deployment unit, and operational complexity for zero architectural benefit. Wait until a second client type with genuinely different needs emerges.
+
+**Simple backend with few services.** If your backend is a single service (monolith or modular monolith) that already returns well-shaped responses, a BFF is pure overhead. The aggregation benefit only materializes when there are multiple downstream services to fan out to. If every mobile screen maps to one backend endpoint, there is nothing to aggregate.
+
+**API Gateway with transformation capabilities suffices.** Modern API gateways (Kong, AWS API Gateway, Apigee) support response transformation, field filtering, and request aggregation at the gateway level. If your "BFF logic" is limited to removing a few fields from responses and combining two endpoints, a gateway transformation policy achieves the same result without a separate service.
+
+**Team does not own or cannot deploy the BFF.** The BFF pattern's organizational benefit depends on the frontend team owning the BFF. If the BFF is owned by a separate "API team" that the mobile team must file tickets with, you have simply moved the coordination bottleneck from the backend team to the BFF team. The organizational structure must match the architectural pattern.
+
+**GraphQL already solves the data-shaping problem.** If your backend exposes a well-designed GraphQL API that lets clients request exactly the fields and relationships they need, and your clients do not need complex multi-service aggregation (because GraphQL resolvers handle it), then adding a BFF on top of GraphQL introduces redundant complexity. As Phil Calcado noted, if your organization uses GraphQL with frontend-specific resolvers, BFF services might not add value.
+
+**Insufficient operational maturity.** Each BFF is a service that must be deployed, monitored, scaled, secured, and maintained. If your team struggles to operate the services they already have, adding more services makes things worse, not better. The BFF pattern is appropriate for organizations that have solved service deployment, monitoring, and incident response — not for those still building that capability.
+
+### Real-World Cautionary Examples
+
+**SoundCloud's BFF proliferation.** SoundCloud themselves discovered the dark side of their pioneering pattern. Over time, business logic migrated into BFFs that should have stayed in backend services. Authorization logic diverged across BFFs. Shared data-fetching code was duplicated rather than centralized. SoundCloud eventually introduced Value-Added Services (domain-oriented services based on DDD principles) to pull business logic back out of BFFs and centralize it where it belonged. The BFFs were reduced to thin orchestration layers. This evolution took years and significant engineering effort.
+
+**The "one BFF per screen" trap.** Some teams interpret BFF as "one backend endpoint per mobile screen." This leads to dozens of screen-specific endpoints that cannot be reused, share no logic, and become a maintenance nightmare. A BFF should serve a client type, not a screen. It should offer a coherent API surface that multiple screens within the same app can consume.
+
+**The shared-library distributed monolith.** A team creates BFFs for web, iOS, and Android, but centralizes authentication, logging, caching, and core business logic into a shared library that all three BFFs depend on. The shared library becomes a coordination bottleneck — any change requires synchronized deployment across all BFFs. The BFFs are independently deployed in theory but coupled in practice. This is a distributed monolith wearing a BFF costume.
+
+---
+
+## How It Works
+
+### BFF Per Client Type
+
+The fundamental structural decision is granularity: how many BFFs, and what does each one serve?
+
+**One BFF per platform family** is the most common and generally safest approach. A "mobile BFF" serves both iOS and Android (since their data needs are usually identical), and a "web BFF" serves the browser client. This is SoundCloud's original model and Netflix's current model.
+
+**One BFF per platform** is justified when iOS and Android have genuinely different data needs — different screen sizes producing different data requirements, platform-specific features like widgets or watch complications that need specialized endpoints, or significantly different release cadences that benefit from independent API evolution.
+
+**One BFF per user experience** is the most granular model. SoundCloud's "listener BFF" and "creator BFF" separated by user role, not by platform. This makes sense when the same platform serves fundamentally different use cases with different data needs.
+
+### Aggregation of Backend Calls
+
+The BFF's primary technical function is call aggregation. Here is the typical flow:
+
+```
+Mobile App                     Mobile BFF                    Backend Services
+    │                              │                              │
+    │  GET /home-feed              │                              │
+    │─────────────────────────────▶│                              │
+    │                              │  GET /users/123/profile      │
+    │                              │─────────────────────────────▶│
+    │                              │  GET /recommendations/123    │
+    │                              │─────────────────────────────▶│
+    │                              │  GET /notifications/count    │
+    │                              │─────────────────────────────▶│
+    │                              │                              │
+    │                              │◀─── all 3 responses ────────│
+    │                              │                              │
+    │                              │  [aggregate, transform,      │
+    │                              │   strip unnecessary fields,  │
+    │                              │   resize image URLs]         │
+    │                              │                              │
+    │  ◀── single optimized ──────│                              │
+    │      response (40KB)         │                              │
+```
+
+The BFF decides which backend calls can be parallelized (user profile + recommendations + notification count) versus which must be sequential (if recommendations depend on user preferences loaded from the profile call). It handles partial failures gracefully — if the notification count service is down, it returns the rest of the data with a null notification count rather than failing the entire request.
+
+### Response Shaping
+
+Response shaping is where the BFF delivers its most visible value for mobile clients:
+
+**Field filtering.** The user service returns 47 fields including internal audit data, admin flags, and legacy compatibility fields. The mobile BFF returns 12 fields — the ones the mobile UI actually renders.
+
+**Image URL transformation.** The product service returns a base image URL. The mobile BFF transforms it to include mobile-appropriate dimensions (`?w=320&h=240&format=webp`) while the web BFF requests full-resolution variants.
+
+**Denormalization.** Backend services return normalized data with foreign key references. The BFF denormalizes — embedding the author's display name directly in each comment object instead of returning a separate author ID that would require another client-side lookup.
+
+**Pagination tuning.** The mobile BFF returns 10 items per page (sized for a mobile screen). The web BFF returns 50 items per page (sized for a desktop viewport with virtual scrolling).
+
+**Localization assembly.** The BFF assembles localized content from the i18n service and embeds it in responses so the mobile app does not need a separate localization lookup per string.
+
+### Authentication Proxying
+
+The BFF acts as an authentication intermediary:
+
+1. The mobile app authenticates with the identity provider (OAuth2, OIDC) and receives a user-facing access token.
+2. The mobile app sends this token to the BFF on every request.
+3. The BFF validates the token, then uses a service-to-service credential (mTLS certificate, internal JWT, API key) to call downstream services.
+4. The mobile app never needs to know about internal service authentication schemes.
+
+This simplifies the mobile app's auth logic and prevents internal service credentials from being exposed on the device. If a backend service migrates from API key auth to mTLS, only the BFF changes — the mobile app's authentication flow remains identical.
+
+### Caching Strategy
+
+BFF-level caching is particularly valuable for mobile because it reduces payload size and network calls:
+
+**Response-level caching.** The BFF caches assembled responses for a short TTL (30-60 seconds for feeds, 5-10 minutes for relatively static data like user profiles). Mobile clients hitting the BFF within the TTL window get instant responses without any downstream calls.
+
+**Backend response caching.** The BFF caches individual backend service responses. If the user profile is needed by both the home feed endpoint and the settings endpoint, it is fetched once and reused.
+
+**ETags and conditional requests.** The BFF generates ETags for assembled responses. Mobile apps send `If-None-Match` headers, and the BFF returns `304 Not Modified` with zero body when nothing has changed — saving bandwidth on metered connections.
+
+**Cache invalidation via events.** The BFF subscribes to backend service events (via message queue or webhook) and invalidates specific cache entries when underlying data changes, rather than relying on TTL expiry alone.
+
+### Error Handling and Graceful Degradation
+
+This is where a BFF provides disproportionate value for mobile clients:
+
+**Partial response assembly.** When one of five backend services times out, the BFF returns the data it has with explicit null markers for the failed section, along with metadata indicating which sections are stale or missing. The mobile app renders what it can and shows a subtle "tap to retry" indicator for the missing section.
+
+**Circuit breaking.** The BFF implements circuit breakers per downstream service. If the recommendations service has been failing for 30 seconds, the BFF stops calling it entirely (open circuit), returns cached recommendations or an empty section, and periodically probes the service to detect recovery.
+
+**Timeout budgets.** The BFF allocates a total timeout budget per request (e.g., 2 seconds). If the mobile app sends a request and the BFF has called 3 of 5 backend services after 1.8 seconds, it cancels the remaining 2 calls and returns a partial response rather than exceeding the mobile app's patience threshold.
+
+**Error translation.** Backend services return implementation-specific error codes and stack traces. The BFF translates these into mobile-friendly error payloads with user-facing messages, error categories (network, auth, validation, server), and retry guidance (retryable: true/false, retryAfterSeconds: 30).
+
+---
+
+## Trade-Offs Matrix
+
+| Dimension | Without BFF | With BFF | Verdict |
+|---|---|---|---|
+| **Network calls per screen** | 3-10 calls from mobile over cellular | 1 call from mobile, fan-out in datacenter | BFF wins decisively on mobile |
+| **Payload size** | Full backend responses with unused fields (200KB+) | Stripped to mobile-needed fields (40KB) | BFF wins, especially on metered connections |
+| **Team autonomy** | Mobile team depends on backend API changes | Mobile team owns their API contract | BFF enables faster mobile iteration |
+| **Operational complexity** | Fewer services to deploy and monitor | Additional service(s) to deploy, scale, monitor | BFF adds operational cost |
+| **Latency (happy path)** | Direct client-to-service (1 hop) | Client-to-BFF-to-services (2+ hops) | BFF adds ~5-20ms but saves multiple round trips |
+| **Error handling** | Mobile app handles partial failures across N calls | BFF aggregates errors, returns graceful fallbacks | BFF centralizes error logic server-side |
+| **Code duplication risk** | N/A | Business logic may leak into multiple BFFs | BFF requires discipline to stay thin |
+| **Caching** | Client-side only, limited by device storage | Server-side + client-side, shared across users | BFF enables more effective caching |
+| **API versioning** | Backend must version for all clients simultaneously | Each BFF versions independently per client type | BFF simplifies versioning |
+| **Testing surface** | Test mobile app against backend directly | Test mobile app against BFF + BFF against backends | BFF increases total test surface |
+| **Deployment coupling** | Mobile release independent of backend | BFF changes may need coordinated deploy | BFF adds deployment coordination |
+| **Security surface** | Mobile app holds service credentials | BFF holds service credentials, mobile holds user token only | BFF reduces credential exposure on device |
+
+---
+
+## Evolution Path
+
+### Stage 1: Direct Client-to-Service
+
+The mobile app calls backend services directly. This works when there are 1-3 backend services, one client type, and a small team. No BFF is needed.
+
+### Stage 2: API Gateway with Lightweight Transformation
+
+As the number of backend services grows to 5-10 and a second client type appears, an API gateway handles routing, auth, and simple response filtering. Gateway-level transformations (field removal, response merging) handle basic client-specific needs. This delays the need for a full BFF.
+
+### Stage 3: Dedicated BFF Per Client Family
+
+When gateway transformations become complex, when different client types need fundamentally different response structures, or when the mobile team's velocity is blocked by API coordination, introduce dedicated BFFs. Start with two: mobile and web. The mobile team owns the mobile BFF. The web team owns the web BFF. Both sit behind the existing API gateway.
+
+### Stage 4: BFF with GraphQL Interface
+
+As the number of mobile screens grows and data requirements become more varied, the BFF may expose a GraphQL interface instead of REST. This lets the mobile app request exactly the fields each screen needs without the BFF needing a dedicated endpoint per screen. The BFF's GraphQL resolvers still aggregate from backend REST/gRPC services. Apollo Federation or schema stitching may connect multiple BFFs into a unified graph.
+
+### Stage 5: Edge BFF / Server-Driven UI
+
+At massive scale (Netflix, Spotify), the BFF evolves toward server-driven UI — the BFF returns not just data but layout instructions, component hierarchies, and rendering metadata. The mobile app becomes a thin rendering shell. This enables A/B testing, personalization, and feature rollout without app store releases. Netflix's Falcor-based BFF and their server-driven UI experiments exemplify this stage.
+
+### Stage 6: BFF Consolidation and Domain Gateways
+
+After operating multiple BFFs for years, organizations often find that business logic has leaked into BFFs, duplicated across them. SoundCloud's evolution is instructive: they introduced Domain Gateways (Value-Added Services based on DDD) that recentralize business logic, reducing BFFs to thin client-specific orchestration layers. This is a maturity step, not a failure of the BFF pattern — it is the natural refactoring that occurs when teams recognize the boundary between "client-specific shaping" and "business logic."
+
+---
+
+## Failure Modes
+
+### 1. The Bloated BFF (Business Logic Migration)
+
+**What happens:** Business rules gradually migrate from backend services into the BFF. Pricing calculations, eligibility checks, authorization logic — developers add them to the BFF because "it is faster than waiting for the backend team." Over months, the BFF becomes a second monolith containing critical business logic that should live in domain services.
+
+**How to detect:** If modifying a business rule requires changing the BFF rather than a backend service, business logic has leaked. If the BFF has database connections, it has almost certainly absorbed business logic.
+
+**How to prevent:** Enforce a rule: the BFF performs aggregation, transformation, and shaping. It never performs calculations, state mutations, or authorization decisions. Those belong in backend services. Code reviews should flag any business logic in BFF PRs.
+
+### 2. The Shared-Library Distributed Monolith
+
+**What happens:** Multiple BFFs share a common library for authentication, logging, data access, and utility functions. The shared library grows to contain most of the actual logic. Updating the library requires coordinated deployment of all BFFs. A bug in the library takes down all client types simultaneously.
+
+**How to detect:** If you cannot deploy one BFF without redeploying others, you have a distributed monolith. If a shared library change requires integration testing across all BFFs, coupling is too high.
+
+**How to prevent:** Shared libraries should contain only truly cross-cutting, stable utilities (logging format, metrics emission). Domain logic, service clients, and data transformation should be duplicated across BFFs or extracted into backend services. Accept small duplication as the price of independence.
+
+### 3. Cascading Failures (Fan-Out Amplification)
+
+**What happens:** A single mobile request triggers the BFF to call 8 backend services. One service responds slowly (30-second timeout instead of 200ms). The BFF thread/connection pool is blocked waiting. Under load, all BFF threads are consumed waiting for the slow service. The BFF becomes unresponsive for all requests, even those that do not need the slow service. The mobile app experiences a total outage.
+
+**How to detect:** Monitor P99 latency per downstream service call from the BFF. If any single backend service can cause BFF-wide latency spikes, fan-out amplification is present.
+
+**How to prevent:** Circuit breakers per downstream service. Timeout budgets per request. Bulkheading — isolating thread/connection pools per downstream service so one slow service cannot exhaust resources needed by others. Return partial responses when a non-critical service is slow.
+
+### 4. The "One BFF Per Screen" Fragmentation
+
+**What happens:** Developers interpret BFF as "create an endpoint for each mobile screen." The mobile app has 40 screens, so the BFF has 40 endpoints with no shared logic, no consistent error handling, and no reusable data-fetching patterns. Adding a new screen requires a new BFF endpoint.
+
+**How to detect:** If the number of BFF endpoints grows linearly with the number of mobile screens, and endpoints share no code, you have screen-level fragmentation.
+
+**How to prevent:** Design BFF endpoints around resources and capabilities, not screens. A `/user/home-feed` endpoint can serve both the home screen and the "pull to refresh" action. A `/product/:id/details` endpoint can serve the product detail screen, the quick-view modal, and the comparison view. The mobile app composes screens from these resource-oriented endpoints.
+
+### 5. BFF as a Bottleneck for Unrelated Changes
+
+**What happens:** The mobile BFF serves both the e-commerce flow and the social features of the app. A change to the social feed endpoint requires deploying the entire BFF, which includes the checkout flow. A bug in the social feed deployment breaks checkout. The blast radius of every BFF deployment is the entire mobile experience.
+
+**How to detect:** If the BFF deployment failure rate increases with the number of features it serves, and failures in one feature area impact unrelated features, the BFF has become a bottleneck.
+
+**How to prevent:** Consider splitting BFFs by domain when they grow beyond a certain complexity. A "commerce BFF" and a "social BFF" have independent deployment and failure domains. Alternatively, use feature flags and canary deployments to limit blast radius.
+
+### 6. Stale Cache Serving Incorrect Data
+
+**What happens:** The BFF caches aggressively to reduce backend load. A user updates their profile, but the cached profile in the BFF still serves the old data for 5 minutes. The user sees stale data after making a change and assumes the update failed.
+
+**How to detect:** User reports of "changes not appearing" after mutations. Discrepancies between what the user just submitted and what the app displays.
+
+**How to prevent:** Cache-busting on writes — when the BFF processes a mutation (POST/PUT/DELETE), it invalidates related cache entries immediately. For user-specific data, use event-driven cache invalidation. For the requesting user specifically, bypass cache on reads that immediately follow writes (read-after-write consistency).
+
+---
+
+## Technology Landscape
+
+### Node.js / Express
+
+The most common BFF runtime. JavaScript/TypeScript on both frontend and BFF means the mobile team (if using React Native) or the web team can write BFF code in their primary language. Express is minimal and well-understood. Downsides: single-threaded event loop means CPU-intensive transformations (large JSON reshaping, image URL generation) can block other requests. Mitigate with worker threads or offloading to a streaming JSON library.
+
+```javascript
+// Express BFF — home feed aggregation
+app.get('/api/mobile/home-feed', authenticate, async (req, res) => {
+  const userId = req.user.id;
+
+  const [profile, recommendations, notifications] = await Promise.allSettled([
+    userService.getProfile(userId),
+    recommendationService.getForUser(userId),
+    notificationService.getUnreadCount(userId),
+  ]);
+
+  res.json({
+    user: profile.status === 'fulfilled'
+      ? shapeForMobile(profile.value)
+      : null,
+    recommendations: recommendations.status === 'fulfilled'
+      ? recommendations.value.slice(0, 10).map(stripToMobileFields)
+      : [],
+    notificationCount: notifications.status === 'fulfilled'
+      ? notifications.value.count
+      : null,
+    _meta: {
+      partial: [profile, recommendations, notifications].some(
+        r => r.status === 'rejected'
+      ),
+    },
+  });
+});
+```
+
+### NestJS
+
+A structured TypeScript framework built on Express (or Fastify). NestJS provides dependency injection, modular architecture, and built-in support for microservice communication (gRPC, NATS, RabbitMQ). For teams that want more structure than raw Express — controller/service separation, interceptors for logging/caching, guards for authentication — NestJS is a strong BFF choice. The `nestjs-bff` open-source boilerplate provides a production-ready starting point with auth, logging, and MongoDB integration out of the box.
+
+### GraphQL as BFF Interface
+
+Instead of REST endpoints, the BFF exposes a GraphQL schema. The mobile app sends GraphQL queries requesting exactly the fields each screen needs. The BFF's resolvers aggregate from backend services.
+
+Advantages: eliminates the need for screen-specific endpoints. The mobile app can request different field sets for the same entity on different screens without BFF changes. Introspection provides self-documentation.
+
+Disadvantages: adds query parsing and validation overhead. Complexity shifts from "too many endpoints" to "query optimization and N+1 prevention." Requires DataLoader patterns to batch backend calls. Caching is harder than REST (no HTTP caching by URL).
+
+Apollo Server, Mercurius (Fastify-based), and AWS AppSync are common GraphQL BFF implementations. Apollo Federation allows composing multiple BFF schemas into a unified graph accessible through a single endpoint.
+
+```graphql
+# GraphQL BFF schema — mobile-optimized
+type Query {
+  homeFeed: HomeFeed!
+  product(id: ID!): Product
+}
+
+type HomeFeed {
+  user: UserSummary
+  recommendations: [ProductCard!]!
+  notificationCount: Int
+}
+
+# Mobile-specific type — only fields the mobile UI renders
+type ProductCard {
+  id: ID!
+  title: String!
+  price: Money!
+  thumbnailUrl: String!   # Pre-sized for mobile
+  rating: Float
+}
+```
+
+### Edge Functions / Serverless BFF
+
+Cloudflare Workers, AWS Lambda@Edge, Vercel Edge Functions, and Deno Deploy allow running BFF logic at the network edge — geographically close to the user. This reduces latency for mobile users by eliminating the round-trip to a centralized BFF server.
+
+Trade-offs: cold start latency (Lambda can add 100-500ms on cold starts, though provisioned concurrency mitigates this), limited execution time, constrained runtime (no long-lived connections, limited memory), and vendor lock-in. Best suited for BFFs that perform lightweight aggregation with low computational overhead. Not appropriate for BFFs with complex orchestration, stateful circuit breakers, or high-throughput requirements.
+
+### Go / Rust for High-Throughput BFFs
+
+When the BFF must handle extreme throughput (100K+ requests/second) or when the aggregation involves significant CPU work (large payload transformation, encryption, compression), Go or Rust BFFs outperform Node.js. Netflix uses Java/Kotlin for some of their BFFs due to JVM ecosystem maturity. Trade-off: the BFF is no longer in the frontend team's primary language, which can reduce the ownership benefit of the pattern.
+
+### Kotlin / Spring Boot (JVM)
+
+For organizations with strong JVM expertise, Spring Cloud Gateway combined with Spring WebFlux provides a reactive, non-blocking BFF framework. Kotlin's coroutines make async aggregation readable. The JVM ecosystem provides mature circuit breakers (Resilience4j), distributed tracing (Micrometer + Zipkin), and service discovery (Eureka, Consul). This is common in enterprises with existing Spring infrastructure.
+
+---
+
+## Decision Tree
+
+```
+START: Do you have multiple client types (mobile, web, TV, partner)?
+  │
+  ├─ NO ──▶ Do you need to aggregate many backend service calls?
+  │           │
+  │           ├─ NO ──▶ STOP. You do not need a BFF.
+  │           │         Use direct API calls or an API gateway.
+  │           │
+  │           └─ YES ─▶ Consider an API gateway with aggregation
+  │                     or a thin orchestration layer. A full BFF
+  │                     is likely overkill for a single client.
+  │
+  └─ YES ─▶ Do different clients need significantly different
+             data shapes, payload sizes, or response structures?
+               │
+               ├─ NO ──▶ Does GraphQL solve your data-shaping needs?
+               │           │
+               │           ├─ YES ──▶ Use GraphQL without BFF.
+               │           │         Clients query what they need.
+               │           │
+               │           └─ NO ───▶ Consider API gateway with
+               │                     per-client transformation rules.
+               │
+               └─ YES ─▶ Can your team operate additional services?
+                           (deploy, monitor, on-call, scale)
+                             │
+                             ├─ NO ──▶ Build operational maturity first.
+                             │         A BFF you cannot operate is worse
+                             │         than no BFF.
+                             │
+                             └─ YES ─▶ Does the frontend team have
+                                       backend development skills?
+                                         │
+                                         ├─ NO ──▶ Invest in team skills
+                                         │         or pair with backend
+                                         │         engineers. BFF ownership
+                                         │         by the frontend team is
+                                         │         critical to the pattern.
+                                         │
+                                         └─ YES ─▶ IMPLEMENT BFF.
+                                                   Start with one BFF per
+                                                   client family (mobile, web).
+                                                   Keep BFFs thin — aggregation
+                                                   and shaping only, no
+                                                   business logic.
+```
+
+---
+
+## Implementation Sketch
+
+### Project Structure (Node.js/TypeScript BFF)
+
+```
+mobile-bff/
+├── src/
+│   ├── controllers/          # Route handlers per feature area
+│   │   ├── home-feed.ts
+│   │   ├── product.ts
+│   │   ├── user.ts
+│   │   └── search.ts
+│   ├── services/             # Backend service clients
+│   │   ├── user-service.ts
+│   │   ├── product-service.ts
+│   │   ├── recommendation-service.ts
+│   │   └── notification-service.ts
+│   ├── transformers/         # Response shaping per entity
+│   │   ├── user-transformer.ts
+│   │   ├── product-transformer.ts
+│   │   └── image-transformer.ts
+│   ├── middleware/
+│   │   ├── auth.ts           # Token validation
+│   │   ├── cache.ts          # Response caching
+│   │   ├── error-handler.ts  # Centralized error translation
+│   │   └── request-id.ts     # Correlation ID propagation
+│   ├── resilience/
+│   │   ├── circuit-breaker.ts
+│   │   ├── timeout.ts
+│   │   └── retry.ts
+│   └── app.ts
+├── test/
+│   ├── controllers/          # BFF endpoint tests (mocked backends)
+│   ├── transformers/         # Response shaping unit tests
+│   └── integration/          # BFF + real/stubbed backends
+├── Dockerfile
+├── package.json
+└── tsconfig.json
+```
+
+### Key Implementation Patterns
+
+**Parallel aggregation with partial failure handling:**
+
+```typescript
+// services/aggregator.ts
+interface AggregationResult<T> {
+  data: T | null;
+  source: string;
+  status: 'ok' | 'timeout' | 'error' | 'circuit-open';
+  latencyMs: number;
+}
+
+async function aggregateWithResilience<T>(
+  calls: Array<{ name: string; fn: () => Promise<T> }>,
+  budgetMs: number = 2000
+): Promise<AggregationResult<T>[]> {
+  const deadline = Date.now() + budgetMs;
+
+  return Promise.all(
+    calls.map(async ({ name, fn }) => {
+      const start = Date.now();
+      const remaining = deadline - start;
+
+      if (remaining <= 0) {
+        return { data: null, source: name, status: 'timeout' as const, latencyMs: 0 };
+      }
+
+      try {
+        const data = await Promise.race([
+          fn(),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error('budget-exceeded')), remaining)
+          ),
+        ]);
+        return { data, source: name, status: 'ok' as const, latencyMs: Date.now() - start };
+      } catch (err) {
+        return {
+          data: null,
+          source: name,
+          status: err.message === 'budget-exceeded' ? 'timeout' as const : 'error' as const,
+          latencyMs: Date.now() - start,
+        };
+      }
+    })
+  );
+}
+```
+
+**Response transformer (strip to mobile-needed fields):**
+
+```typescript
+// transformers/product-transformer.ts
+interface BackendProduct {
+  id: string;
+  title: string;
+  description: string;
+  longDescription: string;
+  internalSku: string;
+  warehouseLocation: string;
+  images: Array<{ url: string; width: number; height: number; format: string }>;
+  pricing: { base: number; discount: number; currency: string; taxRate: number };
+  metadata: Record<string, unknown>;
+  auditLog: Array<{ timestamp: string; action: string }>;
+  // ... 30+ more fields
+}
+
+interface MobileProduct {
+  id: string;
+  title: string;
+  description: string;
+  thumbnailUrl: string;
+  price: string;
+  originalPrice: string | null;
+}
+
+function toMobileProduct(backend: BackendProduct): MobileProduct {
+  const bestImage = backend.images.find(i => i.width >= 320) ?? backend.images[0];
+  const discountedPrice = backend.pricing.base - backend.pricing.discount;
+
+  return {
+    id: backend.id,
+    title: backend.title,
+    description: backend.description.slice(0, 200),
+    thumbnailUrl: `${bestImage.url}?w=320&h=240&format=webp`,
+    price: formatCurrency(discountedPrice, backend.pricing.currency),
+    originalPrice: backend.pricing.discount > 0
+      ? formatCurrency(backend.pricing.base, backend.pricing.currency)
+      : null,
+  };
+}
+```
+
+**Circuit breaker integration:**
+
+```typescript
+// resilience/circuit-breaker.ts
+import CircuitBreaker from 'opossum';
+
+const defaultOptions = {
+  timeout: 3000,           // Trip after 3s
+  errorThresholdPercentage: 50,  // Trip after 50% failures
+  resetTimeout: 30000,     // Try again after 30s
+  volumeThreshold: 10,     // Minimum calls before tripping
+};
+
+// One circuit breaker per downstream service
+const breakers = new Map<string, CircuitBreaker>();
+
+function getBreaker(serviceName: string): CircuitBreaker {
+  if (!breakers.has(serviceName)) {
+    const breaker = new CircuitBreaker(
+      async (fn: () => Promise<unknown>) => fn(),
+      { ...defaultOptions, name: serviceName }
+    );
+
+    breaker.on('open', () => {
+      logger.warn(`Circuit OPEN for ${serviceName}`);
+      metrics.increment(`circuit_breaker.open`, { service: serviceName });
+    });
+
+    breaker.on('halfOpen', () => {
+      logger.info(`Circuit HALF-OPEN for ${serviceName}, probing...`);
+    });
+
+    breaker.on('close', () => {
+      logger.info(`Circuit CLOSED for ${serviceName}, recovered`);
+    });
+
+    breakers.set(serviceName, breaker);
+  }
+  return breakers.get(serviceName)!;
+}
+
+// Usage in service client
+async function callWithBreaker<T>(
+  serviceName: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  return getBreaker(serviceName).fire(fn) as Promise<T>;
+}
+```
+
+---
+
+## Testing Strategy
+
+### Unit Tests: Transformers
+
+Test that response shaping produces the correct mobile-optimized output. These tests are fast, have no network dependencies, and validate the core value proposition of the BFF — that backend responses are correctly transformed for mobile consumption.
+
+### Integration Tests: BFF Endpoints with Stubbed Backends
+
+Use WireMock, MSW (Mock Service Worker), or Nock to stub backend services. Test the full BFF request lifecycle: authentication, aggregation, transformation, caching, and error handling. Verify that partial backend failures produce graceful degraded responses rather than 500 errors.
+
+### Contract Tests: BFF-to-Backend Contracts
+
+Use Pact or similar consumer-driven contract testing. The BFF (consumer) defines the API contract it expects from each backend service (provider). Backend services validate that they satisfy the contract. This prevents backend changes from silently breaking the BFF without requiring full end-to-end tests.
+
+### Load Tests: Fan-Out Behavior Under Stress
+
+BFFs amplify load — one mobile request becomes N backend requests. Load test the BFF with realistic concurrency to verify that circuit breakers trip correctly, connection pools do not exhaust, and response times degrade gracefully rather than catastrophically.
+
+---
+
+## Monitoring and Observability
+
+A BFF must be instrumented more heavily than a typical service because it is the aggregation point — it sees the full picture of backend health from the mobile client's perspective.
+
+**Key metrics to track:**
+
+- **Aggregation latency breakdown:** Time spent in each downstream call, not just total response time. This reveals which backend service is the bottleneck.
+- **Partial response rate:** Percentage of responses returned with one or more sections missing due to backend failure. A rising partial response rate is an early warning.
+- **Cache hit ratio:** Per endpoint and per backend service. Low cache hit rates suggest cache TTLs are too short or cache keys are too specific.
+- **Circuit breaker state transitions:** Track when circuits open, close, and half-open. Frequent state changes indicate an unstable downstream service.
+- **Payload size distribution:** Track response sizes to detect payload bloat. If average mobile response size creeps from 40KB to 200KB, the BFF is accumulating unnecessary data.
+- **Error budget per downstream service:** Track error rates per backend service as seen from the BFF. This is often more accurate than the service's own health metrics because it includes network issues between the BFF and the service.
+
+**Distributed tracing** is non-negotiable. Every BFF request should generate a trace that fans out to show each downstream call, its latency, and its result. Tools: Jaeger, Zipkin, AWS X-Ray, Datadog APM. Without distributed tracing, debugging a slow BFF response requires correlating logs across N+1 services manually.
+
+---
+
+## Cross-References
+
+- **[mobile-app-architecture](../mobile-architecture/):** BFF is one layer in the broader mobile architecture stack. Understanding mobile app architecture patterns (MVC, MVVM, Clean Architecture) clarifies what the BFF replaces on the client side (network layer aggregation, response mapping).
+- **[api-design-rest](../integration/):** BFF endpoints should follow REST design principles for their external interface, even though they aggregate from non-REST backends internally.
+- **[api-design-graphql](../integration/):** GraphQL can serve as the BFF's interface layer. Understanding GraphQL's strengths and weaknesses informs whether to use REST or GraphQL for the BFF's external API.
+- **[microservices](../patterns/):** The BFF pattern exists because of microservices. Without multiple backend services to aggregate, there is no need for a BFF. Understanding microservice decomposition patterns clarifies what the BFF is aggregating.
+- **[api-gateway](../integration/):** API Gateway and BFF are complementary, not competing patterns. Understanding where API Gateway responsibilities end and BFF responsibilities begin is critical to avoiding duplication.
+- **[circuit-breaker](../patterns/):** Circuit breaking is a core resilience pattern within BFF implementations. The BFF is the most natural place to implement circuit breakers for mobile clients.