GraphQL Federation

Evolve relies heavily on GraphQL features, particularly Federation, to provide a flexible backend API. It allows us to provide a single consistent (public) API to the consuming clients, while in the back-end we can be flexible and integrate any composition of services we want.

Implementation pattern

Typically, a federated architecture consists of a GraphQL gateway that loads a supergraph that is composed of several subgraphs, which in turn implement resolvers to integrate with underlaying SAAS services, custom services or sit in front of existing on-prem REST services.

The GraphQL gateway is the accesspoint to any client that interacts with your composable architecture.

Where traditional clients like web and mobile apps interact with the GraphQL gateway directly, AI clients such as LLMs connect through an MCP server. The MCP server translates GraphQL operations into tools that AI agents can discover and invoke using the Model Context Protocol, handling authentication, session management, and rate limiting along the way.

Having a subgraph implement the underlaying services our platform depends on, allows us to define our own data models instead of relying on the data model provided by the external service. This gives us more control and less (vendor) dependency on the underlaying services. This in turn makes it easier for our implementation to Evolve and potentially replace individual subgraphs over time.

Technology stack

Evolve implements Apollo Federation v2, an open specification for composing multiple GraphQL services into a single supergraph. Because the spec is open, each layer of the stack can use the best tool for the job, and individual components can be swapped independently.

Gateway: Apollo Gateway runs the supergraph and handles query planning, routing requests to the right subgraphs, and merging responses.

Subgraphs: each domain service runs GraphQL Yoga as its GraphQL server. Yoga is lightweight and well-suited for subgraph services that don't need the full Apollo Server feature set. Subgraph schemas are annotated with Apollo Federation directives (@key, @extends, @external, and others) using @apollo/subgraph.

Schema management: Hive serves as the schema registry and supergraph delivery layer. Subgraphs publish their schemas to Hive, which composes the supergraph and delivers it to the gateway via CDN. Hive also provides usage analytics and schema change validation.