backend-graphql-patterns

Backend GraphQL Patterns

Purpose

Design production GraphQL schemas with resolvers, DataLoader batching, and auth.

Agent Protocol

Trigger

Exact user phrases: "GraphQL", "schema", "resolver", "query", "mutation", "subscription", "Apollo", "Relay", "GraphQL federation", "GraphQL gateway", "data loader", "N+1 GraphQL", "GraphQL authorization", "GraphQL pagination", "GQL schema design", "GraphQL error handling".

Input Context

Before activating, verify:

• Schema size (number of types, depth of nesting)
• Data sources (primary database, REST APIs, gRPC services, external APIs)
• Authentication and authorization model (RBAC, ABAC, claims-based)
• Client types consuming the API (web SPA, mobile native, third-party, internal services)

Output Artifact

GraphQL schema design with resolver patterns and DataLoader setup as formatted text.

Response Format

# Schema types, queries, mutations

// DataLoader setup
// Resolver patterns
// Auth directive definitions

# Query complexity limits
# Rate limiting rules

No preamble. No postamble. No explanations. No filler/hedging/transitions. Compress output — why use many token when few do trick.

Completion Criteria

• Schema defined with types, queries, mutations, subscriptions
• N+1 query prevention via DataLoader batching
• Auth directives (@auth, @hasRole) applied to schema
• Pagination implemented as cursor-based (Relay edges/node pattern)
• Error handling with typed error codes and partial success
• Query complexity limits and rate limiting configured

Max Response Length

300 lines of schema + resolver code, 50 lines of configuration.

Decision Tree

When to Use GraphQL?

What is the primary API consumer?
  ├── Multiple client types (web, mobile, third-party), different data needs
  │   └── GraphQL — clients control data shape, reduces over/under-fetching
  ├── Single client, well-defined views
  │   └── REST — simpler, cacheable, tooling maturity
  ├── Internal service-to-service communication
  │   └── gRPC — typed contracts, streaming, higher performance
  └── Public API for third-party developers
      └── REST with OpenAPI — industry standard, broad tooling support