graphql

GraphQL — API Development

Activate When

• User invokes /godmode:graphql
• User says "build a GraphQL API", "design schema"
• User says "write a graphql resolver", "resolver", "graphql resolver"
• User says "fix N+1 queries", "add DataLoader"
• User says "set up subscriptions", "federate schema"

Workflow

Step 1: Discovery & Context

# Detect GraphQL framework
grep -l "apollo-server\|graphql-yoga\|mercurius\|\
pothos\|nexus\|type-graphql\|strawberry\|gqlgen" \
  package.json pyproject.toml go.mod 2>/dev/null

# Check for DataLoader usage
grep -rl "dataloader\|DataLoader" src/ 2>/dev/null

# Find schema files
find . -name "*.graphql" -o -name "*.gql" \
  | head -10

GRAPHQL DISCOVERY:
Approach: SDL-first | Code-first
Framework: Apollo | Yoga | Mercurius | Pothos | gqlgen
Consumers: web app | mobile | third-party
Auth: JWT | session | API key
Federation: monolith | gateway + subgraphs

IF no DataLoader and has relations: N+1 is likely
IF no depth limit: production API is vulnerable
IF no complexity limit: one query can DoS the server

Step 2: Schema Design

# SDL-first example
type Query {
  user(id: ID!): User
  users(first: Int!, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

# Every mutation returns payload with errors array
type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

SCHEMA RULES:
  Mutations return payload types (never throw)
  All lists use Relay connections (edges, pageInfo)
  Input types separate from output types
  Non-nullable uses ! intentionally
  Enums for fixed sets, never strings

THRESHOLDS:
  Max query depth: 10 levels
  Max query complexity: 1000 points
  Connection max first/last: 100 items
  IF depth > 10: reject query
  IF complexity > 1000: reject query

Step 3: Resolver Architecture

Resolvers are thin orchestration — no business logic. Business logic lives in service layer.

Step 4: N+1 Detection and DataLoader