Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

The BFF tier: gateway, sessions & fan-out

A Backend for Frontend running in a real system: where it sits behind the API gateway, why it is where a browser's session is held, how it calls five services for one page without letting a slow optional part hold the page, what it caches, and what one more deployable per experience costs.

In front of the gateway, or behind it?

Teams that already run an API gateway ask this the day they add a BFF, and the diagram can be drawn either way. A news publisher is adding one for its website. It already has a gateway in front of a dozen services, among them articles, authors, comments, recommendations and subscriptions.

The gateway handles what every request needs, whichever screen sent it: it terminates TLS, applies rate limits, runs the auth checks that apply to all traffic, and routes by path. That work is the same for the website, the app and partners, so it lives in one place, run by a platform team and mostly configured rather than coded. A Backend for Frontend does the work particular to one experience: it knows the article page needs five things and in what shape, so it is code, owned by the team that owns the website. With the BFF behind the gateway, the gateway sends /web/* to the web BFF and /app/* to the app BFF, and no BFF reimplements rate limiting. API gateway & the edge covers the edge's side.

Whether a client deserves its own BFF at all is the design decision in Backends for Frontends (BFF). This article is about running one: where its session lives, how it calls the services behind one page, and what it costs.

Web BFF behind the gateway

The browser holds only a session cookie. The BFF keeps the tokens server-side and calls the services with an access token.

Where the browser's session lives

The website signs subscribers in through the company's identity provider with OAuth and OpenID Connect, whose flow OAuth 2.0 & OpenID Connect flows follows step by step. The first version did it all in the browser and kept the access and refresh tokens in localStorage, where any script on the page can read them: one cross-site scripting bug, in the site's own code or a third-party script, could copy a subscriber's refresh token and use it from anywhere until it expired or was revoked.

Every call from the website already passes through the BFF, so the BFF is a natural place to keep the tokens instead. It acts as the OAuth client, completes the sign-in, stores the tokens server-side in a session store and gives the browser only a cookie holding an opaque session id, marked HttpOnly and Secure; on each request it looks up the session, attaches the access token to its calls to the services and refreshes it when it expires. The IETF's guidance on OAuth for browser-based apps describes this arrangement under the name BFF.

Three consequences come with it. The browser sends the cookie automatically, so the BFF needs cross-site request forgery defences, such as SameSite cookies and a check on a custom request header. A script injected into the page can still send requests through the subscriber's session while the page is open; what it can no longer do is carry the tokens away. And for the website's traffic, the gateway in front of the BFF no longer sees a token, only a cookie: it keeps TLS and rate limits, while access tokens are checked on the hop after the BFF, by the services or an internal gateway in front of them. How access and refresh tokens expire, rotate and get revoked is Sessions vs tokens: JWT, refresh & revocation.

Five calls behind one page

The article page is where the BFF does most of its work, and where it can hurt. One request from the browser, GET /web/articles/88213, needs the story, the reader's subscription status, the author's profile, the related stories and the comments. Called one after another, at typical latencies of 40, 60, 35, 90 and 120 ms, that is 345 ms before the page has anything. Called in parallel, the page waits for its slowest chain: the author's profile needs the story to name the author (40 + 35 = 75 ms), so the comments' 120 ms set the time.

Parallel calls make the page as slow as its slowest dependency, on every request. If the five services are independent and each is slower than its own 99th percentile on 1 request in 100, a page that waits for all five meets at least one slow call on about 1 request in 20 (1 − 0.99⁵ ≈ 4.9%). Latency percentiles & tail latency explains why the tail is what users feel.

Then the comments service has a bad afternoon: it stops answering, without returning errors. A BFF with no timeouts holds every article page open until the browser, or a proxy on the way, gives up. What a BFF has that Gateway Aggregation at a shared gateway usually lacks is knowledge of the screen, in code the website's team owns, so it knows which parts the page can live without. The web BFF treats the story and the subscription status as required, since without them it cannot decide what to show, and the rest as optional:

  1. The BFF starts each call as soon as it can, each with its own timeout: 300 ms for comments, longer for the story.
  2. The story and subscription calls return; if either had failed, the BFF would return an error and the page would show its error state.
  3. The comments call reaches 300 ms, and the BFF stops waiting for it.
  4. The BFF returns the page with comments marked unavailable rather than as an empty list.
  5. The browser shows "Comments are unavailable" instead of "Be the first to comment".

Marking the gap matters: an empty list would tell readers that nobody has commented, which is false, and invite them into a thread that will not load. The rule holds for any page assembled from parts: a missing part is shown as missing, never as empty, and the whole page fails only when a part it cannot do without fails. When comments stays down for minutes, a circuit breaker lets the BFF skip the call instead of paying 300 ms on every page; Timeout and Circuit Breaker own those two mechanisms.

Caching what the page shows

Most of the article page is the same for every reader, while some parts are personal: whether the reader subscribes, how many free articles they have left this month. Caching the whole response would either show one reader another reader's page or almost never hit, so the BFF caches parts, each with its own lifetime: the story fragment under article:88213 for a few minutes, the comments for seconds or not at all, the personal parts not shared. The assembled response is personal, so it is marked Cache-Control: private and stays out of shared caches such as a CDN; Caching layers covers lifetimes and invalidation.

Six more deployments

A web BFF, an app BFF and a partner BFF, in staging and production, are six more deployments, each needing a pipeline, alerts and on-call cover, and each adds a network hop to its traffic, typically a few milliseconds inside one region and more in the tail. BFF instances keep no state of their own, so any instance can serve any reader and more can be added under load; that makes the session store a dependency of every signed-in page, so it is replicated for availability. If it does go down, the BFF should answer with a temporary error, not treat subscribers as signed out. Plumbing every BFF needs, such as tracing, the OAuth client and default timeouts, comes from one shared template, so each BFF's own code stays the page composition it exists for.

Run a BFF under load and failure

The Micro-Frontend Platform Challenge asks for a backend-for-frontend per experience in front of the downstream APIs, and for a page that survives one broken part. Put a Backend for Frontend between the shell (Micro-frontends: one page, many teams) and the REST APIs for each experience, label each BFF-to-API edge with its timeout and whether the page can render without that API, and make the part whose API is down show a notice instead of blanking the page. The API Gateway Patterns Challenge tests the same boundary from the gateway's side: keep TLS, rate limiting and the auth checks every request needs on the Gateway Offloading node, place a Backends for Frontends node behind the gateway, and label which of the two owns each responsibility.

Practice this