GraphQL Schema Designer

Imported from williamzujkowski/cognitive-toolworks (skills/api-graphql-designer/SKILL.md). Install upstream with npx skills add williamzujkowski/cognitive-toolworks --skill api-graphql-designer. Copyright stays with the author (MIT).

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

2. 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

3. Implement basic pagination:

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

4. Add basic error handling:

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

5. 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

2. 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:

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

3. 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

4. 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)

5. 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

6. 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

2. 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

3. 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:

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

4. 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

5. Performance monitoring instrumentation:

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

6. 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

7. 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:

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:

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

Security directives (if production optimization):

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)

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/