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.

BFF pattern diagram: web, mobile and third-party clients each call their own backend for frontend, which calls shared downstream servicesClients (outside the perimeter)Backends for frontends (one per experience)Desktop web appMobile app (iOS andAndroid)Third-party appWeb BFFMobile BFFPartner API BFFDownstream services(wishlist, catalog,inventory)
BFF pattern: one backend per user experience, each aggregating the same downstream services in its own way. Rendered by ChartCraft's layout engine.

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 diagramWhat it isWhat it does
Desktop web appA browser clientCalls 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 clientCalls only the Mobile BFF. It wants fewer calls and less data, because of screen size, battery and data plans.
Third-party appAn external party's applicationCalls a BFF of its own, so its API can stay stable while the other backends change.
Web BFFThe backend for the web experienceExposes the API the web UI needs and aggregates the downstream calls behind it.
Mobile BFFThe backend for the mobile experienceTurns several downstream calls into one response shaped for the mobile screens.
Partner API BFFThe backend for third partiesPublishes 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 BFFsHold 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 gatewayBackends for frontends
Entry pointsOne, shared by every clientOne per kind of client or experience
Who owns itOften a separate team created to look after itTypically the team that builds that user interface
RiskBecomes a bottleneck as every client's changes land in one deployableDuplicated code between BFFs and more services to run
Good fitClients that make the same or very similar callsClients 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

Skip it when

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.

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.

Opens the studio with your text · or start from the Architecture diagram generator

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.

More patterns and models explained with a diagram

Describe the system in plain English and get the diagram.

Architecture diagram generator →