GraphQL Schema Builder

---
name: graphql-schema-builder
description: |
  Trigger when the user asks to design a GraphQL schema, add GraphQL types,
  or build resolvers. Phrases: "GraphQL schema", "add GraphQL", "define type",
  "resolver", "connection pattern".
allowed-tools:
  - Read
  - Write
  - Grep
---

# GraphQL Schema Builder

Design a GraphQL schema following current community conventions. Pagination
via connections, nullable-unless-necessary, field arguments over top-level.

## Prerequisites

- GraphQL server selected (Apollo, Yoga, Pothos)
- Data model sketched at minimum

## Steps

1. **Start from the query, not the entities.** GraphQL schemas rot when
   built entity-first. List the screens or API consumers and write queries
   they want.

2. **Use nullable fields by default, non-null when necessary.** Marking a
   field non-null is a forward-compatibility lock. Make the contract the
   smallest you can live with.

3. **Pagination: Relay cursor connections.** Do not offset-paginate a public
   GraphQL API. Offset breaks when data mutates. Cursors are stable.

   ```graphql
   type UserConnection {
     edges: [UserEdge!]!
     pageInfo: PageInfo!
     totalCount: Int
   }
   type UserEdge { node: User! cursor: String! }
   type PageInfo {
     hasNextPage: Boolean!
     hasPreviousPage: Boolean!
     startCursor: String
     endCursor: String
   }
   ```

4. **Node interface for globally-unique IDs:**
   ```graphql
   interface Node { id: ID! }
   type User implements Node { id: ID! ... }
   ```

5. **Mutations return payloads, not bare types:**
   ```graphql
   type CreateUserPayload {
     user: User
     clientMutationId: String
     errors: [UserError!]
   }
   ```

   This lets you add fields later without breaking clients.

6. **DataLoader for N+1.** Any resolver that fetches by ID needs a DataLoader
   wrapper. Without it, `{ users { posts { comments } } }` explodes into
   thousands of queries.

## Conventions to follow

- PascalCase for types, camelCase for fields.
- Booleans prefixed with `is` or `has` (`isPublished`, `hasReplies`).
- Enums in SCREAMING_SNAKE_CASE.
- Input types for mutations suffixed `Input` (`CreateUserInput`).
- Never reuse input types for output (or vice versa).

## Output

- `schema.graphql` with Query, Mutation, Subscription root types
- DataLoader set up for at least one N+1 case
- Resolvers implementing the queries
- Example query documented in the README