Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Evolving and Testing

GraphQL Server Architectures

Compare GraphQL server architectures: a server connected to a database, a layer over existing services, the hybrid approach and a backend-for-frontend, with trade-offs and examples.

The lessons so far focused on the schema and its resolvers. One question has stayed in the background: what sits behind the resolvers? A resolver is just a function, and it may read a database, call a REST service, ask a message queue or run a calculation. How you arrange those pieces decides how fast the API is, how easy it is to change and who owns what. This lesson describes the common architectures, when each fits, and the pitfalls to avoid.

The runnable examples are stand-ins in plain JavaScript: fake databases and fake REST services with counters so you can see what each architecture costs in calls. They show the shapes, not production code.

Four common architectures

Database server Resolvers read the database directly.
Integration layer GraphQL in front of existing services.
Hybrid Own data from a database, rest from services.
BFF One graph tailored to one front end.

They can be combined as a system grows.

1 / 2

1. A GraphQL server connected to a database

The simplest architecture is a new application: the GraphQL server is the back end, and resolvers talk to the database directly (through an ORM, a query builder or SQL):

flowchart LR
  C["Client"] --> G["GraphQL server<br/>(schema + resolvers)"]
  G --> D[("Database")]

One server, one database, no extra hops.

This is what the project lessons in this tutorial use. It is the best fit for greenfield products, because you control the schema, the data and the performance. Because the server sees the whole query, it can plan efficient database access, for example with DataLoader batching or even by looking at the selected fields to build one SQL query with joins (SELECT only the requested columns).

Watch for: the schema sliding into a copy of the database tables. A schema should model what clients need, not mirror your table layout (see Schema Design Best Practices). Keep a service layer between resolvers and the database so that business rules are not duplicated in every resolver.

2. An integration layer over existing services

Most organizations already have back ends: REST APIs, SOAP services, gRPC services, a legacy database. A GraphQL server can sit in front of them as an integration layer (also called a gateway or facade). Resolvers call those services and reshape the answers into one coherent graph:

flowchart LR
  C["Clients"] --> G["GraphQL layer"]
  G --> U["Users REST API"]
  G --> O["Orders service"]
  G --> L["Legacy SOAP / DB"]

The graph hides how many systems answer a query.

Clients no longer need to know that user data lives in one system and orders in another, and the old services need no changes. This is often the first step when adopting GraphQL: it is low risk because nothing behind the layer is rewritten.

Watch for: the resolvers become a thin, chatty translation layer. Every field may cost a network call, so the N+1 problem hurts more than with a database (see below). Latency is the sum of the slowest chain of calls. Error handling needs care: a failing service should produce an error on its field and return the rest as partial data. And do not leak the backends' shapes into the schema; design the graph for clients and map in the resolvers.

3. The hybrid approach

Real systems usually combine the two: data your team owns lives in a database the server reads directly, and everything else comes through services:

flowchart LR
  C["Clients"] --> G["GraphQL server"]
  G --> D[("Own database")]
  G --> S["Existing services<br/>(billing, search, legacy)"]

Own the new, wrap the old.

This is a natural migration path: start by wrapping a service, then replace it with your own database-backed code piece by piece, without clients noticing because the schema does not change. The cost is that resolvers have mixed responsibilities, so keep the data access behind small interfaces (a UserRepository whose implementation may call a REST API today and a database tomorrow).

4. Backend for frontend (BFF)

When there are very different clients (a web app, a mobile app, a partner API), one shared graph can become a compromise that suits none of them. The backend-for-frontend pattern gives each client type its own thin GraphQL server, shaped for that client, and each one calls the shared services or a common core:

flowchart LR
  W["Web app"] --> BW["Web BFF"]
  M["Mobile app"] --> BM["Mobile BFF"]
  BW --> S["Shared services"]
  BM --> S

A BFF is owned by the team that owns the client.

The BFF fits teams that ship their client independently: the mobile team can add fields and change aggregation without waiting for others. The price is several servers to run and the risk of duplicated logic, so keep business rules in the shared services and put only presentation and aggregation in the BFF. If you find that all BFFs need the same schema, you probably only need one server.

(Federation, covered in Schema Evolution, Federation and Tooling, is the answer to a different problem: several teams contribute pieces of one shared graph.)

Stand-in: an integration layer and its call count

The first stand-in is an integration layer over two fake REST services. A query for a list of orders with each customer's name is resolved first naively (one call to the users service per order) and then with a per-request batch (one call for all distinct users). The services count calls and simulate latency, so you can see why batching matters even more when the data source is a network service.

Node.js An integration layer: naive versus batched

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Four orders and three distinct customers cost four user calls naively and one when batched. Here the naive calls run in parallel, so the wall-clock time is similar; against a real service with a connection limit, rate limit or per-call cost the gap is much larger. Note also that the layer renamed full_name to name: the schema belongs to the clients, not to the backends.

Stand-in: a hybrid server with partial failure

The second stand-in is a hybrid server. Books come from the "own database" (an array), while review scores come from a legacy service that can fail. A small executor treats a failing field the way GraphQL does: the field becomes null with an error entry, and everything else is returned. Making that field nullable in the schema is what allows this.

Node.js A hybrid graph: own data plus a flaky service

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With the service down, the user still sees titles, and only the score is missing. This is a strong argument for nullable fields on anything that depends on a remote system, as discussed in Lists and Nullability and How Execution Works and How Errors Behave.

Choosing and evolving

Situation Good starting point
New product, you own the data GraphQL server on a database
Many existing services, clients are suffering Integration layer, one service at a time
Gradual replacement of a legacy system Hybrid, hiding the swap behind the schema
Web, mobile and partners with different needs One BFF per client type (or one graph if needs overlap)
Many teams, each owning part of the graph Federation or stitching

Two rules help in every case. First, keep the schema independent from the backends: map names and shapes in resolvers, so you can swap a REST service for a database without a client change. Second, measure the cost per query: log the number of backend calls and the time per resolver, because a layer that hides 40 calls behind one query looks perfect to clients and terrible on the bill. Add caching and query limits before launch.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A company has many REST services and wants to adopt GraphQL with the least risk. Which architecture fits first?

    An integration layer leaves the existing services untouched, so adoption is low risk and can proceed service by service.
  2. 2. What is the main risk of an integration layer over many services?

    Each field may be a network call. Batching, caching and good nullability are essential.
  3. 3. In which situation is a backend-for-frontend (BFF) most useful?

    A BFF lets each client team shape its own graph and move at its own speed, at the cost of more servers.
  4. 4. Why should a field backed by a remote service usually be nullable?

    A non-null field that fails nulls its parent, spreading the damage. Nullable fields isolate the failure.
  5. 5. Which advice keeps a hybrid architecture easy to change?

    If the schema is designed for clients and the sources are hidden, you can replace a service with a database without breaking anyone.

Summary

  • A resolver can read anything, so the real architectural question is what sits behind the resolvers.
  • Database server: simplest for products you own; avoid mirroring tables in the schema.
  • Integration layer: low-risk way to adopt GraphQL over existing services; beware chatty resolvers, N+1 and latency, and use batching and nullable fields.
  • Hybrid: own the new data, wrap the old, and hide the swap behind the schema as a migration path.
  • BFF: one tailored graph per client type, useful for independent client teams; keep business rules in shared services.
  • Keep the schema independent from backends, measure backend calls per query, and add caching and limits before launch.

Next, see how a popular framework wires these pieces together in GraphQL with NestJS.