Grafbase
Product design for a federated GraphQL platform
Grafbase is a platform for building and operating federated GraphQL APIs. It composes many independently owned backend services into one unified graph, with schema checks and governance built in. Its users are backend and platform engineers who own subgraphs and live in pull-request workflows every day.
Founder, Software Engineers, and me
- Product Design
- Systems Thinking
- Prototyping
The feature
Schema Proposals
PR-style review for the GraphQL federation workflow
The problem
Schema changes in a federated graph are high-stakes. One change can ripple across every team and service that composes into it. Federation's composition rules and checks could catch what was technically broken, but they couldn't help the teams agree on a change before it shipped. There was no design-time tool to propose it, discuss it, and sign off on it.
Multiple enterprise clients (teams running large, mission-critical federated graphs) raised the same gap independently: where do we actually review a schema change before it goes live? The demand was clear; the shape of the answer wasn't. So we designed it in collaboration with customers.
Where it belongs
Slack, Notion, or GitHub? None of them fit. The discussion needed a home, and so did the decision: proposing a change, reviewing it, and signing off before it shipped. Slack and Notion detach the conversation from the change, leaving the diff, the line-level context, and the decision state somewhere other than where the schema lives. They also carry no permissions model: no way to define who owns a subgraph, who has to review, or whose approval gates a change.
GitHub isn't universal, so building there would only serve a subset of teams, and it's disconnected from the federated graph anyway, with no knowledge of the gateway, the traces, or the checks that decide whether a change is safe. The schema already lived in Grafbase, where these teams checked metrics, traces, changelogs, and checks every day. So the proposal belonged there, next to the data that tells you whether a change is safe to ship, and where a reviewer is alerted in the same place they'll act on it.
The clickable prototype, 35 frames covering the flow's states, modals, dropdowns, errors, and toasts.
Constraints
What we knew
What we didn't know
What we knew
- Multiple enterprise clients had asked for it.
- The audience (backend devs, platform engineers) already lived in pull-request workflows.
- The Grafbase app was already where they managed the graph.
What we didn't know
- What the right MVP scope was.
- Which edge cases would surface once teams actually used it.
Demand wasn't the question. It was already answered. The question was scope: how much to build for an MVP that stayed coherent without guessing at problems we hadn't heard yet.
System
Rather than invent a new workflow, we borrowed the one these engineers already knew: the pull request. The feature isn't a sprawling new product surface. It's six primitives across two flows. An author proposes a schema change; reviewers discuss and approve it.
Proposal
Putting the change on the table
01Schema diff view
Visualizes the proposed schema change, auto-rebased on the latest published version, so the diff never goes stale.
02Schema checks
Validation, lint, composition, and operation checks run against the proposal. Only approved changes can publish.
03Proposal states
The async state machine every change moves through: draft → under review → approved or rejected.
Review
Discussing it, refining it, accepting it
04Inline comments
Line-level discussion attached to the change itself, so context is line-scoped, not file-scoped. Threads close and stay traceable, never buried.
05Review request + notification
Async collaboration support. Not a feature, but a liveness condition for the workflow.
06Teams + permissions
The governance layer (role-based access control, RBAC): required reviewers, individuals or teams, all of whom must approve before a change can publish.
Iteration
I built a clickable Figma prototype in a week, on purpose: close enough to feel real, easy enough to change, and fast enough to put in front of clients before committing engineering time. The response was strong, so we kicked off iteration rounds with one of those customers, refining the flows against real feedback instead of guesses. The engineers began building the backend in parallel.
Outcome
The approach delivered where it counted: the customer who'd asked for it shaped the MVP through real iteration on the prototype, and we shipped a first version they were happy with. The strongest signal came after launch, when the Grafbase team adopted it internally and used schema proposals regularly across their own subgraphs.
Lessons
One of my favorite books is Steal Like an Artist by Austin Kleon. Its message is that nothing is fully original: every piece of creative work builds on what came before, and new ideas come from reworking what already exists and making it your own.
That held true for this project. I didn't invent a new workflow, I took the pull request flow, something the customers, our engineers, and I all use every day, and adapted it to schema changes. My goal was to shape it so it felt like familiar ground for the developers, and from there, a smoother flow.
See another case study
