Explained with a diagram · API design
BFF pattern: backends for frontends, explained with a diagram
In short
The BFF pattern (backends for frontends) gives each kind of client its own backend service instead of one general-purpose API shared by all of them. A web app, a mobile app and a third-party integration each call a backend built for that one experience, which aggregates calls to the downstream services and returns what that client needs. Each BFF is typically maintained by the team that builds its user interface. The name is credited to Phil Calçado, and Sam Newman described the pattern in 2015.
Updated · by the ChartCraft team · one of the patterns and models explained with a diagram
What does the BFF pattern look like as a diagram?
The diagram has three tiers. Clients are at the top, one backend for frontend per client type is in the middle, and the shared downstream services are at the bottom. Each client talks to exactly one BFF, and every BFF calls the same downstream services on its client's behalf.
Mermaid code for this diagram
flowchart TD
subgraph clients["Clients (outside the perimeter)"]
web["Desktop web app"]
mobile["Mobile app (iOS and Android)"]
partner["Third-party app"]
end
subgraph bffs["Backends for frontends (one per experience)"]
webBff["Web BFF"]
mobileBff["Mobile BFF"]
partnerBff["Partner API BFF"]
end
services["Downstream services (wishlist, catalog, inventory)"]
web --> webBff
mobile --> mobileBff
partner --> partnerBff
webBff --> services
mobileBff --> services
partnerBff --> services
Paste it into any Mermaid renderer, or check and export it with the Mermaid syntax checker and Mermaid to PNG.
What are the parts of a BFF architecture?
There are three kinds of component: the clients, one BFF per user experience, and the downstream services the BFFs call. Think of each user-facing application as two pieces, a client-side app outside your perimeter and its BFF inside it.
| Part of the diagram | What it is | What it does |
|---|---|---|
| Desktop web app | A browser client | Calls only the Web BFF. It has a large screen and a good connection, so it can show more data per request. |
| Mobile app (iOS and Android) | A native client | Calls only the Mobile BFF. It wants fewer calls and less data, because of screen size, battery and data plans. |
| Third-party app | An external party's application | Calls a BFF of its own, so its API can stay stable while the other backends change. |
| Web BFF | The backend for the web experience | Exposes the API the web UI needs and aggregates the downstream calls behind it. |
| Mobile BFF | The backend for the mobile experience | Turns several downstream calls into one response shaped for the mobile screens. |
| Partner API BFF | The backend for third parties | Publishes a separate API for external parties, who often cannot change the calls they make as quickly as your own apps do. |
| Downstream services (wishlist, catalog, inventory) | The services behind the BFFs | Hold the data. In Sam Newman's wish-list example the wishlist service stores each list and its item IDs, the catalog service stores names and prices, and the inventory service stores stock levels. If inventory is down, a BFF can still return the list without the stock indicator. |
What is the difference between a BFF and an API gateway?
An API gateway is a single entry point for all clients. The BFF pattern is a variation of it that defines a separate API gateway for each kind of client, so each one can be shaped and released for one user experience.
| General-purpose API gateway | Backends for frontends | |
|---|---|---|
| Entry points | One, shared by every client | One per kind of client or experience |
| Who owns it | Often a separate team created to look after it | Typically the team that builds that user interface |
| Risk | Becomes a bottleneck as every client's changes land in one deployable | Duplicated code between BFFs and more services to run |
| Good fit | Clients that make the same or very similar calls | Clients whose screens, calls and release cycles differ |
How many BFFs should you have?
The usual guideline is one experience, one BFF. If the iOS and Android apps offer nearly the same experience, they can share a mobile BFF; if they diverge, or separate teams own them, give each its own.
Sam Newman's own preference is strictly one BFF per type of client, because a BFF shared by many kinds of client tends to grow bloated with their different concerns. Team boundaries matter as much as screens: a BFF works best when the team that owns the user interface also owns its backend. The diagram above shows the shared variant, one mobile BFF for both iOS and Android.
When should you use the BFF pattern?
Use it when different clients need different things from the same backend, especially once a mobile app or a third party joins a web UI. With a single client, or clients that make the same requests, it only adds services to run.
Use it when
- A shared, general-purpose backend takes substantial effort to maintain for several interfaces.
- You want to optimise the backend for the needs of one specific client, such as mobile.
- A user interface needs a lot of server-side aggregation of downstream services.
- Third parties need an API that cannot change as often as your own apps do.
Skip it when
- Only one interface talks to the backend.
- Your interfaces make the same or very similar requests.
- You already use GraphQL with frontend-specific resolvers, where a BFF may add little.
- The cost of deploying and operating more services is high.
What are common mistakes with the BFF pattern?
The pattern fails when a BFF stops being specific to one frontend, or when it starts to hold logic that belongs elsewhere.
- Merging BFFs back into one edge API to remove duplication. That recreates the general-purpose backend, with many concerns squashed together.
- Sharing one BFF between many kinds of client. The more client types it serves, the more it bloats.
- Putting cross-cutting features in every BFF. A BFF should hold client-specific logic only; monitoring, authorisation and rate limiting are better handled separately.
- Ignoring partial failure. One BFF call fans out to several services, so decide what to return when one of them is down and make sure the client can render a partial response.
- Giving the BFF to a different team from the frontend it serves, which brings back the cross-team coordination the pattern removes.
- Forgetting the extra hop. Clients no longer call services directly, so check latency against your service-level objectives.
How do you draw a BFF architecture diagram?
Draw the clients in one row, one BFF per client in the next, and the downstream services below, then connect each client to its own BFF and each BFF to the services it aggregates.
What do real service architecture diagrams look like?
Live diagrams from the public ChartCraft gallery, each generated from a plain-English description. Open one to see the prompt that produced it.
Questions
What is the BFF pattern?
The BFF pattern, short for backends for frontends, creates a separate backend service for each frontend interface instead of one general-purpose backend for all of them. Each backend is tailored to one user experience, such as web, mobile or a partner integration.
What does BFF stand for?
BFF stands for backend for frontend. The pattern as a whole is called backends for frontends, because an application usually has several of them, one per kind of client.
What is the difference between a BFF and an API gateway?
An API gateway is one entry point shared by all clients. Backends for frontends is a variation that defines a separate API gateway for each kind of client, so each can expose an API suited to that client and be changed by that client's team.
Should iOS and Android apps share one BFF?
They can if they deliver the same experience and one team owns both; the guideline is one experience, one BFF. If the two apps diverge or belong to different teams, separate BFFs are easier to keep small.
When should you not use the BFF pattern?
Skip it when only one interface uses the backend, or when all interfaces make the same or similar requests. In those cases a single backend or API gateway is simpler and avoids the extra services and the extra network hop.