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.
  • Multi-tenant GraphQL runtime (added 2026-05-15) — the one runtime, many tenant modules alternative. Same ownership-decentralisation goal but with a different topology trade: collapses Federation's per-team server cost (good) at the price of giving up Federation's per-team deploy independence (modules in the same runtime ride one release train). Canonical wiki instance: Airbnb Viaduct. The two patterns are complementary — Viaduct instances can themselves participate as subgraphs in a federated supergraph, collapsing the operational cost while preserving cross-organisation composition. See patterns/module-based-graphql-decentralization for the contribution model.

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

  • sources/2025-07-08-yelp-exploring-chaos-building-a-backend-for-server-driven-ui — Yelp CHAOS subgraph + multi-backend REST fan-out; first wiki instance.
  • — Zalando's UBFF names this pattern as the explicit not-chosen alternative: "instead of having multiple Graphs connected via a library and gateway we have a single service at Zalando which connects all the domains in a single schema Graph." First on-wiki counter- example; see patterns/unified-graphql-backend-for-frontend for the single-service sibling.
  • sources/2026-05-13-airbnb-viaduct-1-0-and-the-future-of-airbnbs-data-mesh — Airbnb's Viaduct 1.0 announcement names this pattern as the complementary alternative — "Federation distributes development by distributing servers. Viaduct distributes development by distributing modules." Viaduct is positioned as composable with Federation: a Viaduct multi-tenant runtime can participate as a subgraph inside a federated supergraph, collapsing per- team server cost (no per-team subgraph server) while preserving Federation's cross-organisation composition at the router. First on-wiki articulation of the Viaduct-runtime-as-Federation-subgraph hybrid topology.
Last updated · 542 distilled / 1,571 read