404kidwiz/graphql-architect

GraphQL Architect Skill

Purpose

Provides expert GraphQL architecture expertise specializing in schema design, federation patterns, resolver optimization, and real-time subscriptions. Builds performant, type-safe GraphQL APIs with N+1 prevention, efficient caching, and scalable API gateway patterns across distributed systems.

When to Use

• Designing GraphQL schema from scratch for new APIs
• Implementing GraphQL federation across multiple services
• Optimizing resolvers to prevent N+1 queries (DataLoader implementation)
• Building real-time features with GraphQL subscriptions
• Migrating from REST to GraphQL or designing hybrid REST+GraphQL APIs
• Implementing GraphQL API gateway patterns

Quick Start

Invoke this skill when:

• Designing new GraphQL schemas or federation architecture
• Solving N+1 query performance issues
• Implementing real-time subscriptions
• Migrating REST APIs to GraphQL

Do NOT invoke when:

• Simple REST API is sufficient (use api-designer)
• Database schema design without API layer (use database-administrator)
• Frontend data fetching only (use frontend-developer)

Core Capabilities

Schema Design

• Creating type-safe GraphQL schemas with best practices
• Implementing pagination patterns (Relay, offset-based)
• Designing mutations with input validation and error handling
• Managing schema evolution and backward compatibility

Federation Architecture

• Implementing Apollo Federation for microservices
• Configuring schema stitching for service composition
• Managing cross-service queries and mutations
• Setting up API gateways for schema composition

Resolver Optimization

• Implementing DataLoader for N+1 prevention
• Caching strategies at resolver and field levels
• Query complexity analysis and depth limiting
• Persisted queries for production optimization

Real-Time Subscriptions

• Implementing WebSocket-based subscriptions
• Managing subscription lifecycle and cleanup
• Integrating with event-driven backends
• Handling subscription authentication and authorization

Decision Framework

GraphQL vs REST Decision Matrix

| Factor | Use GraphQL | Use REST | |--------|-------------|----------| | Client types | Multiple clients with different needs | Single client with predictable needs | | Data relationships | Highly nested, interconnected data | Flat resources with few relationships | | Over-fetching | Clients need different subsets | Clients typically need all fields | | Under-fetching | Avoid multiple round trips | Single endpoint provides enough | | Schema evolution | Frequent changes, backward compat | Stable API, versioning acceptable | | Real-time | Subscriptions needed | Polling or webhooks sufficient |

Schema Design Decision Tree

Schema Design Requirements
│
├─ Single service (monolith)?
│  └─ Schema-first design with single schema
│
├─ Multiple microservices?
│  ├─ Services owned by different teams?
│  │  └─ Apollo Federation
│  └─ Services owned by same team?
│     └─ Schema stitching (simpler)
│
├─ Existing REST APIs to wrap?
│  └─ GraphQL wrapper layer
│
└─ Need backward compatibility?
   └─ Hybrid REST + GraphQL

N+1 Prevention Strategy

Resolver Implementation
│
├─ Field resolves to single related entity?
│  └─ DataLoader with batching
│
├─ Field resolves to list of related entities?
│  ├─ List size always small (<10)?
│  │  └─ Direct query acceptable
│  └─ List size unbounded?
│     └─ DataLoader with batching + pagination
│
├─ Nested resolvers (users → posts → comments)?
│  └─ Multi-level DataLoaders
│
└─ Aggregations or counts?
   └─ Separate DataLoader for counts

Core Workflow: DataLoader Implementation

Problem: N+1 queries killing performance

// WITHOUT DataLoader - N+1 problem
const resolvers = {
  Post: {
    author: async (post, _, { db }) => {
      // Executed once per post (N+1 problem!)
      return db.User.findByPk(post.userId);
    }
  }
};
// Query for 100 posts triggers 101 DB queries

Solution: Batch with DataLoader

import DataLoader from 'dataloader';

// Create loader per request (important!)
function createLoaders(db) {
  return {
    userLoader: new DataLoader(async (userIds) => {
      const users = await db.User.findAll({
        where: { id: userIds }
      });
      // Return in same order as requested IDs
      const userMap = new Map(users.map(u => [u.id, u]));
      return userIds.map(id => userMap.get(id));
    })
  };
}

// Resolver using DataLoader
const resolvers = {
  Post: {
    author: (post, _, { loaders }) => {
      return loaders.userLoader.load(post.userId);
    }
  }
};
// Same query now triggers 2 queries total!

Quick Reference: Schema Best Practices

Pagination Pattern (Relay-style)

type Query {
  users(first: Int, after: String, last: Int, before: String): UserConnection!
}

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

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Error Handling Pattern

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

type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
  code: ErrorCode!
}

enum ErrorCode {
  VALIDATION_ERROR
  NOT_FOUND
  UNAUTHORIZED
  CONFLICT
}

Red Flags - When to Escalate

| Observation | Why Escalate | |-------------|--------------| | Query complexity explosion | Unbounded nested queries causing DoS | | Federation circular dependencies | Schema design issue | | 10K+ concurrent subscriptions | Infrastructure architecture | | Schema versioning across 50+ fields | Breaking change management | | Cross-service transaction needs | Distributed systems pattern |

Additional Resources

• Detailed Technical Reference: See REFERENCE.md

  • Apollo Federation setup workflow
  • Field-level authorization directives
  • Query complexity limiting

• Code Examples & Patterns: See EXAMPLES.md

  • Anti-patterns (N+1 queries, no complexity limits)
  • Integration patterns with other skills
  • Complete resolver implementations