As your application grows, so does your GraphQL schema. What starts as a small, self-contained monolith may eventually need to support multiple teams, services, and domains.

This guide introduces three common patterns for structuring GraphQL APIs at different stages of scale: monolithic schemas, schema stitching, and federation. It also explains how these patterns relate to GraphQL.js and what tradeoffs to consider as your architecture evolves.

Monolithic schemas

A monolithic schema is a single GraphQL schema served from a single service. All types, resolvers, and business logic are located and deployed together.

This is the default approach when using GraphQL.js. You define the entire schema in one place using the GraphQLSchema constructor and expose it through a single HTTP endpoint.

The following example defines a minimal schema that serves a single hello field:

import { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';
 
const QueryType = new GraphQLObjectType({
  name: 'Query',
  fields: {
    hello: {
      type: GraphQLString,
      resolve: () => 'Hello from a monolithic schema!',
    },
  },
});
 
export const schema = new GraphQLSchema({ query: QueryType });

This structure works well for small to medium projects, especially when a single team owns the entire graph. It’s simple to test, deploy, and reason about. As long as the schema remains manageable in size and scope, there’s often no need to introduce additional architectural complexity.

Schema stitching

As your application evolves, you may want to split your schema across modules or services while still presenting a unified graph to clients. Schema stitching allows you to do this by merging multiple schemas into one executable schema at runtime.

GraphQL.js does not include stitching capabilities directly, but the @graphql-tools/stitch package implements stitching features on top of GraphQL.js primitives.

The following example stitches two subschemas into a single stitched schema:

import { stitchSchemas } from '@graphql-tools/stitch';
 
export const schema = stitchSchemas({
  subschemas: [
    { schema: userSchema },
    { schema: productSchema },
  ],
});

Each subschema can be developed and deployed independently. The stitched schema handles query delegation, merging, and resolution across them.

Stitching is useful when:

• Integrating existing GraphQL services behind a single endpoint
• Incrementally breaking up a monolithic schema
• Creating internal-only aggregators

However, stitching can add runtime complexity and often requires manual conflict resolution for overlapping types or fields.

Federation

Federation is a distributed architecture that composes a single GraphQL schema from multiple independently developed services, known as subgraphs. Each subgraph owns a portion of the schema and is responsible for defining and resolving its fields.

Unlike schema stitching, federation is designed for large organizations where teams need autonomy over their part of the schema and services must be deployed independently.

Federation introduces a set of conventions to coordinate between services. For example:

• @key declares how an entity is identified across subgraphs
• @external, @requires, and @provides describe field-level dependencies across service boundaries

Rather than merging schemas at runtime, federation uses a composition step to build the final schema. A dedicated gateway routes queries to subgraphs and resolves shared entities.

GraphQL.js does not provide built-in support for federation. To implement a federated subgraph using GraphQL.js, you’ll need to:

• Add custom directives to the schema
• Implement resolvers for reference types
• Output a schema that conforms to a federation-compliant format

Most federation tooling today is based on Apollo Federation. However, other approaches exist:

• GraphQL Mesh allows federation-like composition across services using plugins.
• Custom gateways and tooling can be implemented using GraphQL.js or other frameworks.
• The GraphQL Composite Schemas WG (formed of Apollo, ChilliCream, The Guild, Netflix, Graphile and many more) are working on an open specification for the next generation of GraphQL Federation

Federation is most useful when schema ownership is distributed and teams need to evolve their subgraphs independently under a shared contract.

Choosing the right architecture

The best structure for your GraphQL API depends on your team size, deployment model, and how your schema is expected to grow.

Migration paths

Architectural patterns aren’t mutually exclusive. In many cases, teams evolve from one approach to another over time.

Monolith to schema stitching

Schema stitching can act as a bridge when breaking apart a monolithic schema. Teams can extract parts of the schema into standalone services while maintaining a unified entry point. This allows for gradual refactoring without requiring a full rewrite.

Stitching to federation

Federation formalizes ownership boundaries and removes the need to manually coordinate overlapping types. If schema stitching becomes difficult to maintain, federation can offer better scalability and governance.

Starting with federation

Some teams choose to adopt federation early, particularly in large organizations with multiple backend domains and team boundaries already in place. This can work well if you have the infrastructure and experience to support it.

Guidelines

The following guidelines can help you choose and evolve your architecture over time:

• Start simple. If you’re building a new API, a monolithic schema is usually the right place to begin. It’s easier to reason about, test, and iterate on.
• Split only when needed. Don’t reach for composition tools prematurely. Schema stitching or federation should be introduced in response to real organizational or scalability needs.
• Favor clarity over flexibility. Stitching and federation add power, but they also increase complexity. Make sure your team has the operational maturity to support the tooling and patterns involved.
• Define ownership boundaries. Federation is most useful when teams need clear control over parts of the schema. Without strong ownership models, a federated graph can become harder to manage.
• Consider alternatives. Not all use cases need stitching or federation. Sometimes, versioning, modular schema design, or schema delegation patterns within a monolith are sufficient.