Skip to content

PATTERN Cited by 2 sources

Federated GraphQL subgraph per domain

When to use

You have:

  • A GraphQL supergraph that many teams share.
  • Multiple product domains (search, billing, content, notifications, …) each owned by a different team.
  • Pressure to ship per-domain schema changes without coordinating across all teams.
  • A supergraph router (Apollo Federation or equivalent) that can compose schemas.

The pattern

One subgraph per domain, owned by the domain team. Each subgraph:

  • Declares the types and fields the domain owns.
  • Runs as its own service with its own deploy cadence.
  • Implements its own resolvers, authenticated at the router or inside the subgraph.
  • Can have arbitrarily different backends behind it (REST APIs, databases, message queues) — the GraphQL shape is a facade.

The supergraph router composes the subgraph schemas into a single schema, dispatches fields to owning subgraphs, and presents one endpoint to clients.

Canonical wiki instance: Yelp CHAOS

Yelp's CHAOS server-driven-UI framework is one subgraph in Yelp's Apollo Federation supergraph:

  • Subgraph: a Python service built on Strawberry, owning the chaosConfiguration query and the ChaosView, ChaosJsonComponent, ChaosJsonAction types.
  • Backends behind the subgraph: "multiple CHAOS backends that implement a CHAOS REST API" — one REST backend per owning team, not one Python service. The subgraph routes the request to the right backend based on the requested view name.
           clients (iOS / Android / web)
                     │
                     ▼
           ┌──────────────────────┐
           │ Apollo Federation    │
           │ router (supergraph)  │
           └──────┬──────┬────────┘
                  ▼      ▼
        ┌─────────────┐  ┌─────────────┐
        │ CHAOS       │  │ other       │
        │ subgraph    │  │ subgraphs   │
        │ (Python,    │  │ (search,    │
        │ Strawberry) │  │  billing…)  │
        └─────┬───────┘  └─────────────┘
              │  CHAOS REST API
              ▼
        ┌───────────────────────┐
        │ N CHAOS backends      │  ← one per owning team
        │ (team-owned services) │
        └───────────────────────┘

Verbatim (2025-07-08): "This federated architecture allows us to manage our CHAOS-specific GraphQL schema independently while seamlessly integrating it into Yelp's broader Supergraph. Behind the GraphQL layer, we support multiple CHAOS backends that implement a CHAOS REST API to serve CHAOS content … This architecture allows different teams to manage their CHAOS content independently on their own services, while the GraphQL layer provides a unified interface for client requests."

This is one level deeper than the older unified GraphQL API platform pattern — the subgraph itself is a thin facade that fans out to multiple team-owned REST backends, rather than being the single owner of its domain's data.

Contrast with adjacent patterns

  • Single-owner subgraph — one team owns the subgraph and the backend. Simpler; doesn't scale to product areas like CHAOS where many teams contribute content.
  • Schema stitching / API gateway — the router merges multiple upstream schemas without the Federation directives; works but has well-documented composition issues at scale.
  • Backend-for-frontend — a client-specific facade, not a domain-specific one. Different axis.

Hard problems this pattern introduces

  • Two-level ownership. The subgraph is owned by one framework team (CHAOS), but the content lives in many team-owned backends. Latency, error handling, and deploys cross this boundary on every request.
  • Cross-backend cross-feature queries. When a view combines features from multiple backends, the subgraph must orchestrate the fan-out; see patterns/two-loop-parallel-async-build.
  • Schema stability is load-bearing. Frequent schema changes ripple to the router, tooling, and every client. Systems built on this pattern often also adopt concepts/json-string-parameters-for-schema-stability to decouple payload evolution from schema evolution.

Seen in

Last updated · 476 distilled / 1,218 read