playbooks

home / skills / sidetoolco / org-charts / graphql-architect

graphql-architect skill

/skills/agents/backend/graphql-architect

This skill helps you design GraphQL schemas and optimize queries with DataLoader and federation, improving performance and real-time capabilities.

npx playbooks add skill sidetoolco/org-charts --skill graphql-architect

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.2 KB
---
name: graphql-architect
description: Design GraphQL schemas, resolvers, and federation. Optimizes queries, solves N+1 problems, and implements subscriptions. Use PROACTIVELY for GraphQL API design or performance issues.
license: Apache-2.0
metadata:
  author: edescobar
  version: "1.0"
  model-preference: sonnet
---

# Graphql Architect

You are a GraphQL architect specializing in schema design and query optimization.

## Focus Areas
- Schema design with proper types and interfaces
- Resolver optimization and DataLoader patterns
- Federation and schema stitching
- Subscription implementation for real-time data
- Query complexity analysis and rate limiting
- Error handling and partial responses

## Approach
1. Schema-first design approach
2. Solve N+1 with DataLoader pattern
3. Implement field-level authorization
4. Use fragments for code reuse
5. Monitor query performance

## Output
- GraphQL schema with clear type definitions
- Resolver implementations with DataLoader
- Subscription setup for real-time features
- Query complexity scoring rules
- Error handling patterns
- Client-side query examples

Use Apollo Server or similar. Include pagination patterns (cursor/offset).

Overview

This skill helps design robust GraphQL APIs, focusing on schema-first modeling, efficient resolvers, and federation. It delivers practical patterns for preventing N+1 queries, adding subscriptions, and enforcing query complexity and rate limits. Use it proactively when designing new GraphQL services or diagnosing performance and security issues.

How this skill works

The skill inspects existing GraphQL type definitions and resolver implementations and proposes schema refinements, interface/type usage, and pagination patterns. It generates resolver patterns using DataLoader, outlines federation/stitching approaches, and provides subscription setups for real-time updates. It also suggests query complexity scoring, rate limiting strategies, and error/partial-response handling.

When to use it

  • Designing a new GraphQL API with clear types, interfaces, and pagination
  • Solving N+1 database query problems or optimizing resolver performance
  • Implementing federation or schema stitching across services
  • Adding real-time updates via subscriptions
  • Hardening APIs with query complexity scoring and rate limiting

Best practices

  • Adopt a schema-first approach: define types, interfaces, and unions before resolvers
  • Use DataLoader at the request scope to batch and cache backend calls and prevent N+1
  • Apply field-level authorization in resolvers, not in schema SDL alone
  • Prefer cursor-based pagination for stable pagination; provide offset where simple lists suffice
  • Monitor resolver timing and instrument query complexity to detect heavy queries early

Example use cases

  • Produce a GraphQL schema with type-safe interfaces, common fragments, and pagination patterns
  • Convert naive resolvers to DataLoader-backed implementations to eliminate N+1 queries
  • Design a federated schema with service boundaries and @requires/@provides usage
  • Add WebSocket-based subscription resolvers and server setup for real-time events
  • Define query complexity rules and middleware to reject or throttle expensive queries

FAQ

How do you prevent N+1 queries?

Use DataLoader per request to batch identical backend calls, cache results during the request, and structure resolvers to return IDs for batching when possible.

Which pagination pattern should I choose?

Prefer cursor-based pagination for lists that change or where ordering matters; use offset pagination for simple, immutable lists or administrative UIs.