williamzujkowski/GraphQL Schema Designer

Purpose & When-To-Use

Trigger conditions:

• Designing new GraphQL API schema from domain model
• Converting REST APIs to GraphQL
• Implementing Apollo Federation for microservices
• Optimizing GraphQL queries for n+1 problems
• Setting up schema stitching across multiple GraphQL services
• Implementing real-time subscriptions
• Adding field-level authorization and security
• Migrating monolithic GraphQL to federated architecture
• Designing BFF (Backend for Frontend) GraphQL layer

Not for:

• GraphQL client implementation (use Apollo Client, Relay, urql)
• GraphQL server deployment/infrastructure (use platform-specific tools)
• Database query optimization (use database-specific skills)
• Real-time transport protocols (WebSocket, SSE configuration)

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601): 2025-10-26T03:51:54-04:00
• Use NOW_ET for all citation access dates

Input validation:

• schema_type must be exactly: "standalone", "federated", or "stitched"
• use_case if provided must be one of: "api-gateway", "microservices", "mobile-bff"
• optimization_level must be: "basic" or "production"
• entities if provided must be valid array of objects with name, fields, relationships
• federation_config required if schema_type is "federated"

Source freshness:

• GraphQL Specification October 2021 (accessed 2025-10-26T03:51:54-04:00): https://spec.graphql.org/October2021/
• Apollo Federation v2 Documentation (accessed 2025-10-26T03:51:54-04:00): https://www.apollographql.com/docs/federation/
• DataLoader GitHub (accessed 2025-10-26T03:51:54-04:00): https://github.com/graphql/dataloader
• GraphQL Best Practices (accessed 2025-10-26T03:51:54-04:00): https://graphql.org/learn/best-practices/

Procedure

T1: Basic Schema Design (≤2k tokens)

Fast path for 80% of standalone GraphQL schema cases:

1. Define core types from entities:

• Create GraphQL object types from domain entities
• Map field types to GraphQL scalars (Int, Float, String, Boolean, ID)
• Add custom scalars for Date, DateTime, JSON, URL as needed
• Mark non-nullable fields with ! based on business rules

1. Create Query and Mutation root types:

• Design query resolvers for single entities (by ID) and collections (list, filtered)
• Design mutation resolvers for CRUD operations (create, update, delete)
• Follow naming conventions: getUser, listUsers, createUser, updateUser, deleteUser
• Add Input types for mutation arguments

1. Implement basic pagination:

• Offset-based pagination for simple use cases: limit, offset arguments
• Return totalCount for UI pagination controls

1. Add basic error handling:

• Use union types for operation results: type UserResult = User | NotFoundError | ValidationError
• Or use nullable fields with errors extension pattern

1. Generate SDL output:

• Format schema using GraphQL SDL
• Include comments for field descriptions
• Group related types together

Output: Basic GraphQL schema SDL with queries, mutations, and types

Token budget: ≤2k tokens (type definitions + basic resolvers)

T2: Production Optimization & Federation (≤6k tokens)

Extended implementation with n+1 prevention and federation:

1. Apply T1 basic schema design first

1. Implement DataLoader patterns for n+1 prevention (accessed 2025-10-26T03:51:54-04:00):

• Create DataLoader instances for batch loading: new DataLoader(batchLoadFn)
• Batch database queries by keys: SELECT * FROM users WHERE id IN (?)
• Cache results per-request to avoid duplicate fetches
• Handle one-to-many relationships with batching
• Example resolver with DataLoader:

javascript { User: { posts: (parent, args, { dataloaders }) => dataloaders.postsByUserId.load(parent.id) } }

1. Design cursor-based pagination (Relay-style):

• Implement Connection pattern with edges, pageInfo, cursor
• Use base64-encoded cursors for opaque pagination
• Support first, after, last, before arguments
• Return hasNextPage, hasPreviousPage in pageInfo

1. Add Apollo Federation v2 configuration (if federated) (accessed 2025-10-26T03:51:54-04:00):

• Mark entity types with @key directive: type User @key(fields: "id") { id: ID! }
• Define reference resolvers for entity lookup: __resolveReference(reference)
• Use @shareable for common types across subgraphs
• Use @external and @requires for field dependencies
• Design subgraph boundaries by domain (users, products, orders)

1. Implement authorization directives:

• Create custom @auth directive for field-level security
• Add role-based access: @auth(requires: ADMIN)
• Implement in directive resolver or schema transformer

1. Query complexity analysis:

• Calculate query cost based on depth and breadth
• Set complexity limits to prevent abuse
• Use query depth limiting (e.g., max depth 7)
• Implement query cost analysis plugin

Output: Production-ready schema with federation, DataLoaders, pagination, and security

Token budget: ≤6k tokens (T1 + optimization patterns + federation setup)

T3: Advanced Patterns & Subscriptions (≤12k tokens)

Deep dive with schema stitching, subscriptions, and advanced optimization:

1. Apply T2 production optimization first

1. Schema stitching patterns (if stitched) (accessed 2025-10-26T03:51:54-04:00):

• Merge multiple GraphQL schemas into unified gateway
• Use schema delegation for remote subschema queries
• Implement type merging for common entities across services
• Handle schema conflicts with type renaming or field aliasing
• Configure batch execution for delegated queries

1. GraphQL subscriptions design (accessed 2025-10-26T03:51:54-04:00):

• Define Subscription root type for real-time events
• Use PubSub mechanism for event publishing: pubsub.publish('USER_UPDATED', payload)
• Implement subscription resolvers with AsyncIterator
• Filter subscriptions by user context or arguments
• Example subscription:

graphql type Subscription { userUpdated(userId: ID!): User newOrder: Order @auth(requires: ADMIN) }

1. Advanced resolver patterns:

• Field-level resolver composition with middleware
• Resolver caching strategies (in-memory, Redis)
• Lazy loading for expensive computed fields
• Custom scalar resolvers (DateTime, Email, URL validation)
• Error handling middleware for consistent error responses

1. Performance monitoring instrumentation:

• Add resolver timing metrics
• Track DataLoader cache hit rates
• Monitor query complexity scores
• Log slow queries for optimization

1. Advanced federation patterns:

• Implement extended service schemas for backward compatibility
• Use @override for gradual service migration
• Design for distributed tracing across subgraphs
• Handle authentication/authorization propagation

1. Schema evolution strategies:

• Add deprecation notices: field: String @deprecated(reason: "Use newField")
• Version schema changes without breaking clients
• Implement schema registry for federated governance

Output: Complete enterprise-grade GraphQL architecture with subscriptions, stitching, and monitoring

Token budget: ≤12k tokens (T2 + subscriptions + stitching + advanced patterns)

Decision Rules

When to use standalone vs. federated:

• Standalone: Single domain, small team, monolithic backend, simple data model
• Federated: Multiple teams/services, domain-driven design, microservices architecture, independent deployment

When to use schema stitching vs. federation:

• Stitching: Integrating third-party GraphQL APIs, legacy schema integration, heterogeneous services
• Federation: Homogeneous subgraphs, shared entity model, strong type safety, Apollo ecosystem

n+1 detection triggers:

• Nested list queries returning multiple items
• One-to-many or many-to-many relationships in schema
• Resolver executes database query in a loop

Pagination strategy selection:

• Offset: Simple use cases, small datasets, admin interfaces
• Cursor: Large datasets, infinite scroll, real-time data, bi-directional pagination

Stop conditions:

• If entities is empty and no existing schema: ERROR "Cannot generate schema without entity definitions"
• If federation_config missing for federated type: ERROR "Federation config required for federated schema"
• If custom scalars lack validation logic: WARN "Custom scalar validation recommended"
• If query depth >10: WARN "Consider query depth limiting"

Output Contract

Required fields:

yaml
schema_definition: |
  # GraphQL SDL string with complete schema
  type Query { ... }
  type Mutation { ... }
  type User { ... }
resolver_patterns:
  dataloader_setup: "Code pattern for DataLoader initialization"
  batch_loading: "Batch loading function examples"
  error_handling: "Error handling middleware pattern"
optimization_config:
  dataloader_enabled: boolean
  query_complexity_limit: integer
  depth_limit: integer
  pagination_type: "offset | cursor"
  caching_strategy: "per-request | redis | none"

Additional fields for federated:

yaml
federation_config:
  version: "v2"
  subgraph_name: string
  entities: array
  shared_types: array
  directives_used: ["@key", "@shareable", "@external"]

Security directives (if production optimization):

yaml
security_directives:
  - name: "@auth"
    description: "Field-level authorization"
    locations: ["FIELD_DEFINITION", "OBJECT"]
  - name: "@rateLimit"
    description: "Rate limiting per field"
    locations: ["FIELD_DEFINITION"]

Type definitions:

• schema_definition: string (GraphQL SDL)
• resolver_patterns: object with code snippets
• optimization_config: object with configuration values
• federation_config: object (only if schema_type is "federated")
• security_directives: array of directive definitions

Examples

Example: Federated User Service Schema (≤30 lines)

graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0",
        import: ["@key", "@shareable"])

type User @key(fields: "id") {
  id: ID!
  email: String!
  posts: [Post!]! # Resolved via DataLoader
}

type Post @key(fields: "id") {
  id: ID!
  title: String!
  authorId: ID! @external
}

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

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

scalar DateTime

Quality Gates

Token budgets (enforced):

• T1 basic schema: ≤2k tokens
• T2 production optimization: ≤6k tokens
• T3 advanced patterns: ≤12k tokens

Schema validation:

• ] SDL syntax valid (parse with graphql-js)
• ] All field types resolve to defined types or scalars
• ] No circular dependencies without proper resolution
• ] Query and Mutation root types present
• ] Input types for all mutation arguments

Federation validation (if federated):

• ] All entities have @key directive
• ] Reference resolvers implemented
• ] No conflicting @shareable types
• ] External fields properly marked

Performance checks:

• ] DataLoader configured for all relationship fields
• ] Pagination implemented for list queries
• ] Query complexity analysis enabled
• ] Depth limiting configured (max 7-10)

Security gates:

• ] No sensitive data in query arguments (use input types)
• ] Authorization directives on protected fields
• ] Input validation for custom scalars
• ] Error messages don't leak sensitive information

Determinism:

• Same inputs produce identical SDL output
• Directive ordering consistent
• Type definitions alphabetically sorted within groups

Auditability:

• All schema changes tracked with @deprecated notices
• Breaking changes documented
• Migration guides for deprecated fields

Resources

GraphQL Specification & Best Practices:

• GraphQL Specification (October 2021): https://spec.graphql.org/October2021/
• GraphQL Best Practices: https://graphql.org/learn/best-practices/
• GraphQL Schema Design Guide: https://www.apollographql.com/docs/apollo-server/schema/schema/

Apollo Federation:

• Apollo Federation v2 Documentation: https://www.apollographql.com/docs/federation/
• Federation Subgraph Specification: https://www.apollographql.com/docs/federation/subgraph-spec/
• Managed Federation Guide: https://www.apollographql.com/docs/federation/managed-federation/overview/

DataLoader & Optimization:

• DataLoader GitHub Repository: https://github.com/graphql/dataloader
• Solving the n+1 Problem: https://www.apollographql.com/blog/backend/data-sources/a-deep-dive-on-apollo-data-sources/
• Query Complexity Analysis: https://github.com/slicknode/graphql-query-complexity

Schema Stitching:

• Schema Stitching Documentation: https://www.graphql-tools.com/docs/schema-stitching/stitch-combining-schemas
• GraphQL Tools: https://www.graphql-tools.com/

Authentication & Authorization:

• GraphQL Authorization Patterns: https://graphql.org/learn/authorization/
• Auth Directives Guide: https://www.apollographql.com/docs/apollo-server/security/authentication/

Subscriptions:

• GraphQL Subscriptions Spec: https://spec.graphql.org/October2021/#sec-Subscription
• Apollo Subscriptions: https://www.apollographql.com/docs/apollo-server/data/subscriptions/