Overview

Let's dive into the architecture of a supergraph.

In this lesson, we will:

• Identify the key pieces of a supergraph, what each piece does and where it's hosted
• Describe how a round-trip request and response works from the client to the supergraph

Starting from a GraphQL API

Let's take a look at how a GraphQL API currently works.

When a client needs some data, it sends a GraphQL operation to the GraphQL server. The server uses its schema, resolvers, and data sources to retrieve and resolve that data, then sends it back to the client. It's a pretty great experience!

In the previous lesson, we talked about using GraphOS to help us get insight into our supergraph (and more!). All GraphOS needs is an existing GraphQL API!

When we plug it into GraphOS, our API is transformed into a supergraph.

What's in a supergraph?

A supergraph has a modular architecture, which means it's composed of one or more modules. A module has its own schema, resolvers, and data sources. Sound familiar? It should, that's essentially a GraphQL server! Specifically, we call these modules by another name: subgraphs.

A subgraph is usually focused on a specific business domain. In our case, the Poetic Plates API is one such module which is all about serving recipe content.

A supergraph can have many subgraphs; it all depends on your API's features and capabilities. We have big dreams for Poetic Plates involving more subgraphs in the future!

To query data from subgraphs, we need another key component: the router.

The router is responsible for accepting incoming operations from clients, figuring out which subgraphs can resolve which parts of the operation, and sending these smaller parts to the appropriate subgraphs.

The router acts as the single endpoint that clients can send their queries to. Clients shouldn't have to worry about communicating with the subgraphs in a supergraph!

And that's how things work in a supergraph!

Where GraphOS fits in

Remember, GraphOS is the platform that lets us manage and scale our supergraph. To get started, we provide it with our existing GraphQL API, which becomes the first subgraph in our supergraph.

Behind the scenes, GraphOS will provision, host and maintain the router for us, which is really handy. Specifically, it'll create an instance of the Apollo Router, host it somewhere, then provide us with the URL endpoint that we can use to query it.

Because it's hosted on GraphOS, it's also referred to as the cloud router. You might also hear the term cloud-hosted supergraph. Both refer to the same thing: GraphOS takes care of hosting for us!

On the other hand, we're responsible for hosting our subgraphs. We can use any hosting platform that suits our needs. For example, the Poetic Plates API is hosted on Heroku.

Practice

Key takeaways

• The supergraph architecture is composed of one or more subgraphs and a router.
• The client sends a GraphQL operation to the router. The router receives this request, figures out which subgraphs are responsible for resolving it, and sends the operations to the appropriate subgraphs. The subgraphs resolve the data and return it to the router, which then bundles it up to return to the client.
• GraphOS provisions and hosts the router, which is an instance of the Apollo Router. When GraphOS hosts the router, it's also called the cloud router.

Up next

We're ready to transform our GraphQL API into a supergraph with the help of GraphOS!