Engineering GraphQLFederationSchema Design

GraphQL Architect

GraphQL schema design, resolvers, federation, subscriptions, DataLoader patterns, caching strategies, and security with query cost analysis.

A GraphQL architect who designs schemas that are easy to evolve without breaking clients, implements DataLoader to eliminate N+1 query problems at the resolver level, and sets up Apollo Federation for composing multiple subgraph services. Adds query complexity analysis and depth limits to prevent expensive query attacks.

Added Mar 20, 2026

$npx skills add johnefemer/skillfish --skill graphql-architect

Capabilities Real Examples Get Started Models & Context Works Great With

What This Skill Can Do

Concrete capabilities you get when you install this skill.

Design GraphQL schemas with clear ownership, nullability, and deprecation strategy

Implement DataLoader for batching and caching resolver database calls

Set up Apollo Federation with subgraph services and the router gateway

Build GraphQL subscriptions over WebSockets with Redis pub/sub for scaling

Add query complexity scoring, depth limits, and rate limiting for security

Configure persisted queries and response caching with Apollo Server or Yoga

Real Conversations

See how the GraphQL Architect skill responds to actual requests. These are representative examples of what your AI agent will produce.

You

My GraphQL resolver for Post.author is making a separate database query for every post in a list. I have 50 posts and it's generating 51 queries. How do I fix this with DataLoader?

Agent

DataLoader batches multiple resolver calls made in the same event loop tick into a single batched database call:

import DataLoader from 'dataloader';
import { PrismaClient } from '@prisma/client';

// Create one DataLoader per request (never globally — caches are request-scoped)
export function createUserLoader(prisma: PrismaClient) {
  return new DataLoader<string, User>(async (userIds) => {
    const users = await prisma.user.findMany({
      where: { id: { in: userIds as string[] } },
    });
    // DataLoader requires results in the SAME ORDER as keys
    const userMap = new Map(users.map(u => [u.id, u]));
    return userIds.map(id => userMap.get(id) ?? new Error(`User ${id} not found`));
  });
}

// Attach to request context
const server = new ApolloServer({
  context: ({ req }) => ({
    prisma,
    loaders: {
      user: createUserLoader(prisma),
    },
  }),
});

// Resolver — calls load(), DataLoader batches automatically
const resolvers = {
  Post: {
    author: (post, _args, { loaders }) => loaders.user.load(post.authorId),
    // 50 posts → 50 calls to loaders.user.load() → batched into 1 SQL query
  },
};

Key rules:

Create loaders per request, not globally — the cache is per-request
The batch function must return results in the same order as the input keys
Return Error instances for missing keys, not null — DataLoader surfaces them correctly

You

A user sent a deeply nested query that caused our GraphQL server to make 10,000 DB calls and brought down the service. How do I prevent this?

Agent

Layer three defenses — depth limit, complexity limit, and query allowlisting for production:

1. Depth limiting (blocks deeply nested queries):

import depthLimit from 'graphql-depth-limit';

const server = new ApolloServer({
  validationRules: [depthLimit(10)], // reject queries nested > 10 levels
});

2. Query complexity analysis (blocks expensive but shallow queries):

import { createComplexityPlugin } from 'graphql-query-complexity';

const server = new ApolloServer({
  plugins: [
    createComplexityPlugin({
      maximumComplexity: 1000,
      estimators: [
        fieldExtensionsEstimator(),
        simpleEstimator({ defaultComplexity: 1 }),
      ],
      onComplete: (complexity) => console.log('Query complexity:', complexity),
    }),
  ],
});

// On the schema, annotate expensive fields:
type Query {
  users(limit: Int): [User!]! @complexity(value: 10, multipliers: ["limit"])
}

3. Persisted queries (most secure — production only):

// Only allow pre-registered query hashes in production
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
// Server: reject any query not in the allowlist

Quick triage for your immediate incident:

// Add request timeout to kill runaway queries
const server = new ApolloServer({
  context: () => ({
    // Per-request Prisma instance with a statement timeout
    prisma: new PrismaClient({
      datasources: { db: { url: process.env.DATABASE_URL } },
    }).$extends({ query: { $allOperations: async ({ query, args }) => {
      return Promise.race([query(args), new Promise((_, r) => setTimeout(() => r(new Error('Timeout')), 5000))]);
    }}})
  }),
});

Get Started

How to install and use this skill in your preferred environment.

Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase.

Models & Context

Which AI models and context windows work best with this skill.

Recommended Models

Claude Sonnet 4 or GPT-4o for schema design and DataLoader patterns. Apollo Federation configuration is complex — verify subgraph directives against the current Apollo docs.

Context Window

SKILL.md ~5KB. Federation gateway configuration with multiple subgraphs benefits from 64K+ context.

Pro tips for best results

1

Be specific

Include numbers — users, budget, RPS — so the skill can size the architecture.

2

Share constraints

Compliance needs, team size, and existing stack all improve the output.

3

Iterate

Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.

4

Combine skills

Pair with companion skills below for end-to-end coverage.

Works Great With

These skills complement GraphQL Architect for end-to-end coverage. Install them together for better results.

Senior Backend

REST APIs, database optimization, authentication, and microservices.

BackendAPIs

Senior Frontend

React, Next.js, TypeScript, Tailwind CSS, accessibility, and performance.

FrontendReact

Database Designer

Schema analysis, ERD generation, index optimization, and migrations.

DatabaseSchema

API Design Reviewer

REST API linter, breaking change detector, and design scorecard.

APIReview

Performance Profiler

Node/Python/Go profiling, bundle analysis, and load testing.

PerformanceProfiling

$ skillfish add johnefemer/skillfish --all # install all skills at once

Ready to try GraphQL Architect?

Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.