Federated GraphQL Supergraph

Overview

As an organization grows, a single monolithic GraphQL schema becomes a bottleneck: every team must coordinate changes through one codebase. GraphQL federation solves this by letting teams own independent subgraphs that a gateway composes into a single supergraph. Clients query one endpoint and see a unified graph; behind it, ownership is distributed.

Use this when multiple teams expose related domains (users, catalog, orders, reviews) and you want one client-facing graph without a central schema team gatekeeping every change.

Components

• GraphQL gateway: receives queries, plans them across subgraphs, and stitches results.
• Subgraph services: domain-owned GraphQL servers, each publishing a partial schema with federation directives.
• Schema registry: validates and composes subgraph schemas, blocking breaking changes before they ship.
• Istio: provides mTLS, traffic routing, and observability between gateway and subgraphs on Kubernetes.
• PostgreSQL: per-subgraph datastores following database-per-service.
• Redis: caches persisted-query results and entity lookups.
• Prometheus: collects per-resolver and per-subgraph latency metrics.

Data Flow

The gateway parses an incoming query, consults the composed supergraph to build a query plan, and dispatches sub-queries to the relevant subgraphs. Entities are resolved across boundaries using key fields and reference resolvers. Partial results return to the gateway, which assembles the final response. Persisted queries and entity caches in Redis cut repeated downstream fan-out.

Scaling and Resilience

Subgraphs scale independently as Kubernetes deployments with horizontal pod autoscaling. The gateway is stateless and scales horizontally behind the mesh ingress. Query depth limits, complexity analysis, and per-client rate limits protect subgraphs from expensive queries. Timeouts and partial-result handling let the graph degrade gracefully when one subgraph is unhealthy.

Security

Istio enforces mutual TLS between all services. The gateway validates OIDC tokens and forwards scoped claims to subgraphs, which apply field-level authorization. Persisted queries restrict production clients to a vetted query set, shrinking the attack surface. The schema registry prevents accidental exposure of internal fields by gating composition in CI.

Trade-offs and Alternatives

Federation introduces a query-planning layer and operational complexity in the registry and gateway. For a single team or a small graph, a monolithic GraphQL server or even REST is simpler. Schema stitching is a lighter-weight alternative but lacks the entity-resolution guarantees of true federation. Over-deep or N+1 query patterns must be actively managed or they erode the benefits.