---
name: graphql-schema-architect
description: "A production-shaped GraphQL schema designed from your domain: entity types with deliberate nullability, relationships modelled as fields, paginated lists, mutation payloads with errors, and auth-aware operations, with a comment explaining each design choice. Use when a new GraphQL API needs its schema designed from a domain description and entity relationships, with pagination, mutation payloads, and auth decisions made up front. Do not use for auditing or refactoring a schema that already exists, or generating resolver code. Related topics: coding, graphql."
---

# GraphQL Schema Architect

A production-shaped GraphQL schema designed from your domain: entity types with deliberate nullability, relationships modelled as fields, paginated lists, mutation payloads with errors, and auth-aware operations, with a comment explaining each design choice.

## When to use

Use this skill when a new GraphQL API needs its schema designed from a domain description and entity relationships, with pagination, mutation payloads, and auth decisions made up front. Do not use it for auditing or refactoring a schema that already exists, or generating resolver code.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Translate each entity into an object type with an ID and the fields the domain implies, choosing non-null only where the server can always supply the value.
3. Model every relationship as fields on the relevant types, using connection types for lists that can grow when pagination is on.
4. Design root Query fields around how clients fetch and root Mutation fields around user intents, each mutation with one input type and a payload type carrying user errors.
5. Add enums for closed sets, interfaces for shared behaviour, and custom scalars with their format described.
6. Mark operations requiring authentication, state where the depth limit applies, and put a description on every type and field.

## Inputs

- **Domain description** (longer free text)
- **Primary entities** (choose any: User, Product, Order, Category, Review, Payment, Subscription, Notification)
- **Other entities** (free text, e.g. "Any entity not listed above")
- **Relationships** (longer free text)
- **Authentication method** (choose one: JWT, API Key, Session Cookie, None)
- **Include pagination** (choose one: Yes, No)
- **Maximum depth for nested queries** (number from 1 to 10)

## Output

One fenced graphql block containing the complete SDL with descriptions on every type and field, followed by a short list of the design decisions and the trade-off each one makes.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### GraphQL Schema Architect

Design a GraphQL schema from my domain, with the reasoning written into the SDL.

#### Details
- Domain description: {{Domain description}}
- Primary entities: {{Primary entities}}
- Other entities: {{Other entities}}
- Relationships: {{Relationships}}
- Authentication method: {{Authentication method}}
- Include pagination: {{Include pagination}}
- Maximum depth for nested queries: {{Maximum depth for nested queries}}

Model the entities as object types with a non-null ID and the fields the domain description implies, making a field non-null only when the server can always provide it. Express each relationship as a field on both sides when clients need to traverse both ways, and as a paginated connection (first and after arguments with edges and pageInfo) wherever a list can grow, when pagination is on. Design the root Query around how clients fetch (by ID, by list with filters) and the root Mutation around user intents (placeOrder, not updateOrder), each mutation taking one input type and returning a payload type that carries the result and a user errors list. Use enums for closed sets, interfaces where types share behaviour, and declare custom scalars (DateTime, Money) with a comment on their format. Mark operations that require the chosen auth method with a comment or an @auth directive and say where the depth limit is enforced. Write a description string on every type and field so the schema documents itself.

## Pitfalls

- Mirroring database tables one to one, so the schema exposes join tables and foreign keys instead of the domain clients think in.
- Returning a bare object from mutations, which leaves no place for validation errors other than the top-level errors array.
- Making every field non-null for convenience, so one failed sub-resolver nulls out the whole response.
