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 underlying 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.

graph TD;
    web<-->graphql-gateway
    mobile-app<-->graphql-gateway
    LLM<-->mcp-server["MCP Server"]
    mcp-server<-->graphql-gateway
    graphql-gateway<-->supergraph
    supergraph<-->subgraph1
    supergraph<-->subgraph2
    supergraph<-->subgraph3
    subgraph1<-->SAAS-service
    subgraph2<-->custom-service
    subgraph3<-->existing-REST-service

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 underlying 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 underlying 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: a custom Hive Router binary written in Rust (backend/services/graphql-gateway), with the Evolve plugins compiled in. It runs the supergraph and handles query planning, routing requests to the right subgraphs, and merging responses. In development the supergraph is composed locally with the Hive CLI (task supergraph → supergraph.generated.graphql); in production the router polls the supergraph from the Hive CDN. The router also enforces persisted documents in production (require_id: true, backed by Hive App Deployments), rejecting any operation not registered in the Hive CDN.

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.