Federation Architecture Overview

Why One Graph Stops Working at Team Scale

A five-person team can keep one GraphQL schema coherent because somebody holds the whole graph in their head. At forty engineers across catalog, checkout, and accounts that same schema becomes a shared build artifact: every team reviews every schema change, every release ships every resolver, and one runaway query in catalog can starve checkout because both run in one process against one connection pool.

Federation removes the coupling without removing the single graph clients depend on. Each team runs a subgraph — an ordinary GraphQL server with its own schema, resolvers, datastore, and release cadence. A build step composes every subgraph schema into one supergraph, and a gateway serves that supergraph as the only endpoint clients talk to.

before                              after

+-------------------------+        client --- one endpoint, one schema
| one schema              |            |
| one resolver map        |            v
| one deploy, one DB      |     +--------------+
| 40 engineers commit     |     |    gateway   |  plans, then fans out
+-------------------------+     +--------------+
                                   |      |      |
                                 catalog checkout accounts
                                 subgraph subgraph subgraph
                                 (own DB) (own DB) (own DB)

Clients see no difference: one endpoint, one document, one type system, one error shape. Ownership changes on the inside. The catalog team edits catalog types and deploys catalog alone, and a slow checkout query cannot exhaust catalog's database because they are separate processes with separate resources.

Subgraphs do not import each other's resolvers, migrations, or tables. The only thing they share is type definitions — and only the subset needed to reference each other, which the next topic defines precisely. Federation buys that team autonomy at the price of a composition step in CI, a gateway you now have to operate, and at least one extra network hop per operation. Whether the trade is worth it depends on team topology more than on request volume; see stitching versus federation for the lighter alternative and the org shapes where it wins.

The Four Pieces and One Request Path

Four nouns carry the entire architecture:

Take a product page query that spans three subgraphs:

query ProductPage($id: ID!) {
  product(id: $id) {          # products subgraph
    name                      # products subgraph
    reviews {                 # reviews subgraph, via entity hop
      rating
      author {                # accounts subgraph, second hop
        displayName
      }
    }
  }
}

The gateway does not forward that document verbatim to anyone. It plans first:

client --query--> gateway
                    |-- fetch 1 --> products  { product(id: $id) { id name } }
                    |-- fetch 2 --> reviews   representations: [{Product, id}]   after 1
                    |-- fetch 3 --> accounts  representations: [{User, id}]      after 2
                    <-- merged response shaped exactly like the original query ---

Each fetch is a plain GraphQL operation against one subgraph. Subgraphs never call each other; only the gateway fans out, which keeps the cross-service traffic in one place where it can be planned, traced, cached, and rate limited. Fields the gateway already has — Product.id from fetch 1 — are shipped to reviews as an entity representation instead of being fetched again.

Two consequences matter in production. First, an operation touching three subgraphs costs at least three sequential round trips, so cross-subgraph depth shows up directly in latency. Second, because planning happens before execution, an operation whose shape the gateway has seen before is served from a plan cache rather than re-planned, and that cache hit rate is one of the first numbers worth watching.

Drawing Ownership Lines, and When Not to Federate

Good boundaries follow two forces: who owns the data, and how often the thing changes. Boundaries drawn by entity count produce subgraphs that must deploy together anyway, which reintroduces the coupling federation was supposed to remove.

Rules that hold up in practice

• One team owns one subgraph. Shared ownership of a subgraph is the old monolith with extra latency.
• Every field has exactly one owning subgraph. Two owners means composition cannot decide who resolves it.
• A type that appears in more than one subgraph needs a key so the gateway can hop between them.
• Avoid cycles where A's entity requires B's, which requires A's. The plan degenerates into long sequential chains.
• Two subgraphs that always ship in the same release should be one subgraph until they stop.

What federation costs you

• The gateway becomes critical path infrastructure: it needs redundancy, a warmed plan cache, and its own dashboards.
• A schema registry or at minimum a CI composition step becomes mandatory, because composition failures otherwise surface at deploy time.
• Local development gets heavier — you now run several subgraphs plus a gateway to exercise a single page.
• Debugging spans processes: a single client operation becomes several traces, so distributed tracing stops being optional.

When to skip it. One team, one or two services, one deploy unit: a modular monolith gives you the same code-level boundaries with none of the infrastructure, and you can always extract later. Federation earns its keep when multiple teams need to change their slice of the graph without negotiating a shared release. If you cannot name a second team that would benefit, you do not need federation yet — and you will pay the gateway tax for nothing.

Interviewers like to probe exactly this boundary. A strong answer names both sides: federation is an organizational scaling tool first and a performance tool never — it adds hops, so it makes individual operations slower while making teams faster.