Skip to main content

Subgraph boundaries — Conway's Law is the API

Where you cut your subgraphs determines whether federation liberates your teams or gives them a distributed monolith. The cut is organisational first, technical second.

The rule: one subgraph per team-owned domain​

A subgraph boundary is a deployment boundary, an on-call boundary and a schema-change boundary. All three must belong to the same team, or you've created a shared artifact with diffuse ownership — the exact problem federation exists to solve.

Good cuts:

  • catalog, pricing, inventory, orders, identity, search — nouns a product person recognizes, each with an accountable team.

Bad cuts we see in the wild:

  • By layer: a database-subgraph and an aggregation-subgraph. That's an architecture diagram, not a domain — every feature change now touches both.
  • By deployment convenience: "these three services share a cluster so they share a subgraph." Infrastructure topology leaks into your API contract.
  • The common subgraph: a dumping ground for types nobody owns. It grows forever and every team is blocked on it. If a type has no owner, you've found an org question to answer, not a subgraph to create.

Size heuristics​

  • A subgraph a team can't rewrite in a quarter is too big.
  • A subgraph that exposes fewer than ~5 types and never changes is probably a partition of convenience — merging it into its closest domain removes a hop and an on-call rotation.
  • More subgraphs than teams is a warning sign. (More teams than subgraphs is fine — teams can own two domains.)

Entities are the seams — keep them thin​

Cross-subgraph entities (Product, User, Order) are your coupling points. Every field added to an entity by a non-owner increases the blast radius of change (ownership rules). Design pressure should always push fields toward the owner and keep contributed fields to genuinely-owned data.

Don't federate what doesn't need federating​

Federation is a solution to an organisational scaling problem — many teams, one graph. If you have one team and 30 types, a well-modularized monolithic graph is simpler, faster (no plan hops) and cheaper to operate. We have told multiple clients not to adopt federation; it's in the audit template. Adopt it when:

  • more than ~3 teams ship schema changes, and deploy-train contention is measurable, or
  • you're merging previously separate graphs (acquisitions, platform consolidation), or
  • clear domains have materially different scaling/runtime needs.

Migration order (when coming from a monolith graph)​

  1. Router in front, monolith becomes "subgraph zero" — zero client impact, day one.
  2. Peel off the domain with the fewest entity relationships first (often identity or content) — cheap lessons.
  3. Save the entity-dense core (orders, product) for last, when your composition CI, tracing and rollback muscles exist.
  4. Never migrate a domain and redesign its schema in the same step. One variable at a time.