1. Airlock, the Monolith


Welcome to the second course of our Voyage series!

In the first course, we learned about , how it works and how it helps us modularize our and scale faster. We built an app called FlyBy using federation from day one!

In this course, we'll explore how federation can help solve problems in an existing, non-federated . We'll learn how to transform this existing into a federated graph (otherwise known as a supergraph).

To give us the observability and governance that we need to manage and build a federated , we'll power up our API with Apollo GraphOS. Apollo GraphOS is a complete cloud platform for building, managing, and scaling your : it provides a set of tools and services so that product developers can focus on building better apps, faster. We'll be using to manage our graph, work with it locally, and migrate types and from our schema safely using the @override .

Check your plan: Part of this course covers the self-hosted router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won’t be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.

Before we get started, you should already be familiar with the following concepts that were covered in the first course of this series:

  • What is
  • The components of a : and the
  • Using the

Note: This series is intended for backend developers who are comfortable working with an existing .

If you're a frontend developer who doesn't work on the backend, the good news is that your workflow stays the same, whether you're dealing with a federated or a non-federated . You'll still send all your to a single endpoint, and the backend team will handle the rest!

All right, let's dive into what we're working with!

πŸͺ Introducing Airlock, our space travel app

Want to book a trip to new, exciting, sometimes-fictional places in the vast universe? Enter Airlock!

The Airlock app homepage with a list of places to book.

Using Airlock, you can find listings that meet your dates of choice and the number of beds you'll need. Learn what each place is all about and what amenities it offers, and if you're interested, you can book your stay in one click (provided you have enough space credits in your wallet of course)!

If you're looking to rent out your own space suite, you can do that with Airlock too! Add your listing to the platform with all the necessary details and start managing your bookings. After each stay, guests and hosts will leave honest ratings and reviews about each other.

Airlock's evolution story

Behind the scenes, Airlock's architecture looks something like this:

Diagram of Airlock's architecture showing one web client connected to the GraphQL server which in turn connects to multiple services

Airlock started out as a basic app with a small that defined very few types and . As its popularity and usage grew, new features were introduced, along with schema changes and additions.

Soon enough, the small unassuming app transformed into an unwieldy monolith. The developer experience is degrading as friction starts to creep in - schema changes and improvements are met with merge conflicts, inconsistencies and duplicated information. It's becoming difficult to navigate the large schema file! New features and bug fixes are taking longer to deploy.

Illustration of a small application that has transformed into an intimidatingly huge monster representing the monolith graph

The may look small in the diagram, but in reality, it more closely resembles a big monolith monster with many different business domains represented as types, queries, and all contained in a single humongous .graphql file!

Additionally, we have multiple teams and developers responsible for these business domains. Let's meet a couple of them and what they're struggling with.

  • πŸ‘©πŸ½β€πŸš€ The Accounts Team says:

    "We're in charge of all things related to users, accounts, and user profiles! We think it's a fairly small scope to work within, so it's been a pain having to sift through all the other business domains in the schema that don't involve our intended changes."

  • πŸ‘©πŸ½β€πŸ« The Listings Team says:

    "We deal with all the cool space rentals in Airlock: their information, amenities, and linking them back to a profile (which the Accounts team is responsible for). We definitely own a big chunk of what's in the schema right now and we make a lot of changes with new features and improvements! Oftentimes, we have merge conflicts with other teams."

There are a few more teams involved with Airlock development: the Bookings team, the Reviews team, and the Payments team. It's clear that all of them struggle with developing, growing, and scaling the as it stands.

To help our Airlock developers have a smoother experience, we're going to transform this monolith into a ! We should already be familiar with the benefits of a federated architecture outlined in the first course, and those same benefits apply here!

An alternate journey of the supergraph

If you're not familiar with the journey of an through the , you can review it in Voyage I.

Our journey for this course will be similar to the one in the previous course, with one big exception: we're going to be starting from a monolith that we'll split incrementally into multiple .

Let's revisit the journey!

A doodle demonstrating the journey of converting the monolith into a subgraph and publishing it to the registry to generate a supergraph schema

First, the monolith will be converted into a . This means all of the schema's types, , and behavior will still be preserved and working as usual.

Next, we're going to publish the to the registry. This triggers .

If fails, we get error messages we'll need to fix! If composition succeeds, Uplink will be updated with our new .

Then, the will fetch this schema and be ready to handle incoming queries using this new schema!

This is only the start of our journey! After this process, we'll go back to the start and split off another from the monolith subgraph. After we make changes to a subgraph, we'll need to publish our again and follow the flow.

πŸ“‹ The migration plan

Let's go over the implementation specifics for how to transform our large monolith into a !

First and foremost, we want to make sure that throughout this process, the web app client doesn't experience any issues and that queries continue to work as normal!

Here are the high-level steps for our migration plan:

  1. We'll convert the monolith into a , which we'll run on a different port. (Yes, it's valid for a to have just one subgraph!) This subgraph will be published to the schema registry.

  2. We'll create a running on the monolith's original port. The router will be connected to the schema registry and will handle all of the same queries that were previously being sent to the monolith server.

  3. We'll start to split off small chunks of our single monolith into new domain-specific subgraphs. This will take several steps, which we'll explain in more detail later on.

Does this process sound familiar to you? These steps apply the Strangler Fig approach - a migration technique that involves incrementally replacing an old system with new components until the old system is "strangled" and can be completely removed.

Diagram illustrating the steps outlined above


Which of these are common problems that developers experience with a monolithic GraphQL schema?

Key takeaways

  • A simple schema can potentially evolve into a big, intimidating schema that is difficult to navigate and work with for different teams. Federation solves these problems, but the process will be different when starting with an existing application compared to a green app.

  • We want to avoid any issues with the client by following a migration plan that swaps the original monolith server with the .

  • At the beginning, our will be composed of only one : the initial monolith schema.

Up next

Before we can get the migration plan into action, let's get Airlock up and running!


Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.