docs / grandstack-federation / Start

grandstack-federation: overview

GraphQL federation for GRANDstack. The Neo4j server becomes a subgraph, a small Wikipedia subgraph is added, and a gateway composes them, so one query returns movie and person data from Neo4j together with a Wikipedia summary, image and page link.

Federation overview

Clients (grandstack-web, agents, curl) send one query to the gateway.
The gateway (Hive Gateway) serves the composed supergraph on port 4000 and plans each query.
supergraph.graphql is composed from the two subgraphs by npm run compose and committed.
The Neo4j subgraph is grandstack-server with FEDERATION=true; Movie and Person are keyed on wikipediaTitle.
The Wikipedia subgraph adds a wikipedia field to Movie and Person and calls the public Wikipedia API.
seed/wikipedia-links.cypher stores each film’s and person’s Wikipedia page at server start.

{
  movies(where: { title: { eq: "Heat" } }) {
    title released
    wikipedia { description extract pageUrl thumbnailUrl }
  }
}

returns the film from Neo4j and "1995 crime drama film by Michael Mann" from Wikipedia. A film or person with no link (for example Madonna) gives wikipedia: null, with no error.

Needs internet. The Wikipedia part calls the live public Wikipedia API. Content, descriptions and rate limits are Wikipedia’s, and its text is available under CC BY-SA 4.0 (show the pageUrl when you display it). The stack is open, with no auth; see auth and agents.

Run it

Clone grandstack, grandstack-server, grandstack-web and this repo side by side into one folder, then start the stack from the grandstack folder:

mkdir grand-stack && cd grand-stack      # any folder name
for repo in grandstack grandstack-server grandstack-web grandstack-federation; do git clone https://github.com/grand-stack/$repo; done
cd grandstack
docker compose -f compose.yaml -f compose.federation.yaml up --build

Open	What
http://localhost:4000/graphql	The gateway: the one endpoint for everything (the web app uses it too)
http://localhost:3000	`grandstack-web`, unchanged, now talking to the gateway
http://localhost:4001/graphql	The Neo4j subgraph, for development
http://localhost:4010/graphql	The Wikipedia subgraph, for development

The first start of the gateway needs a gateway/supergraph.graphql; the committed one works as it is. After changing either subgraph’s schema, run npm run compose (see composition). With the stack up, run npm ci and then npm run smoke inside the grandstack-federation folder.

Documentation

Read	To learn
How it works	The pieces, one federated query step by step, auth and agents
The subgraphs	The `FEDERATION` setting, the `@key`, the Wikipedia subgraph, caching, errors
Linking films and people to Wikipedia	The link builder, matching rules, coverage, what is not matched
Composition and the gateway	`npm run compose`, the supergraph, addresses, when to recompose
What we tried	Mesh’s OpenAPI handler, version pins, and why the Wikipedia subgraph is hand-written
Recipes	Link another entity, add another subgraph
Exercise: show Wikipedia in grandstack-web	A follow-up task for a developer or coding agent
Testing	Unit tests, the smoke script
Troubleshooting	Errors we hit and their fixes

Working with a coding agent? Start with AGENTS.md.

Last verified: grandstack-federation v0.1.1 with grandstack-server v0.9.0, grandstack-web v0.5.1, Hive Gateway 2.15.2, Mesh compose CLI 1.8.4, @apollo/subgraph 2.14.4, Neo4j 2026.10 community, under Podman 6 on macOS.

Licence

Apache License 2.0. See LICENSE and NOTICE. The same licence applies to every GRANDstack repository and to grandstack.ai.

Source: grandstack-federation/README.md (this page is a copy; edit it in the repository)