curiositech/graphql-server-architect

GraphQL Server Architect

Design production-grade GraphQL APIs with efficient data loading, real-time subscriptions, and federated schema architecture.

Activation Triggers

Activate on: "GraphQL", "DataLoader", "subscription", "federation", "schema stitching", "resolver", "SDL", "Apollo Server", "GraphQL Yoga", "Pothos", "query complexity"

NOT for: REST API design → api-architect | Frontend GraphQL client → relevant frontend skill | Database queries → data-warehouse-optimizer

Quick Start

1. Choose framework — GraphQL Yoga 5.x (lightweight), Apollo Server 4.x (ecosystem), Mercurius (Fastify)
2. Schema-first or code-first — SDL for team collaboration, Pothos/Nexus for type-safe code-first
3. Implement DataLoader — batch and cache per-request to solve N+1 queries
4. Set query complexity limits — prevent clients from requesting arbitrarily deep/wide queries
5. Add persisted queries — lock down production to known queries, improve CDN caching

Core Capabilities

| Domain | Technologies | |--------|-------------| | Servers | GraphQL Yoga 5.x, Apollo Server 4.x, Mercurius 14+ | | Schema | Pothos (code-first), SDL (schema-first), GraphQL Codegen | | Federation | Apollo Federation 2.8+, GraphQL Mesh, Schema Stitching | | Performance | DataLoader, @defer/@stream, persisted queries, query complexity | | Real-Time | GraphQL Subscriptions (WebSocket), graphql-ws, SSE transport |

Architecture Patterns

DataLoader Pattern (N+1 Prevention)

import DataLoader from 'dataloader';

// Create per-request DataLoader
function createLoaders() {
  return {
    userById: new DataLoader<string, User>(async (ids) => {
      // Single batch query instead of N queries
      const users = await db.query('SELECT * FROM users WHERE id = ANY($1)', [ids]);
      const map = new Map(users.map(u => [u.id, u]));
      return ids.map(id => map.get(id) ?? new Error(`User ${id} not found`));
    }),
  };
}

// Resolver uses loader — automatically batched
const resolvers = {
  Post: {
    author: (post, _, { loaders }) => loaders.userById.load(post.authorId),
  },
};

Apollo Federation 2 (Supergraph)

Clients
   ↓
Apollo Router (supergraph)
   ├─→ Users Subgraph     (owns User type)
   ├─→ Orders Subgraph    (extends User with orders)
   └─→ Products Subgraph  (owns Product type)

Each subgraph is an independent GraphQL service.
Router composes query plans across subgraphs.

# Users subgraph
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}

# Orders subgraph — extends User from Users subgraph
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]!
}

type Order {
  id: ID!
  total: Float!
  status: OrderStatus!
}

Query Complexity Limiting

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const complexityLimit = createComplexityLimitRule(1000, {
  scalarCost: 1,
  objectCost: 10,
  listFactor: 20,
  onCost: (cost) => {
    if (cost > 800) logger.warn(`High complexity query: ${cost}`);
  },
});

const server = createYoga({
  schema,
  validationRules: [complexityLimit],
});

Anti-Patterns

1. No DataLoader — resolvers that query the DB individually create N+1 problems; always batch with DataLoader
2. Unbounded queries — without depth/complexity limits, a single query can join your entire graph and crash the server
3. Exposing internal IDs — use opaque Relay-style global IDs, not raw database primary keys
4. Fat resolvers — resolvers should delegate to service/repository layers, not contain business logic
5. Subscription over-fetching — do not broadcast full objects; send minimal change payloads and let clients re-query

Quality Checklist

• [ ] DataLoader used for all relationship resolvers (no N+1)
• [ ] Query depth limit set (max 10-15 levels)
• [ ] Query complexity limit enforced (reject expensive queries)
• [ ] Persisted queries enabled in production (no arbitrary queries from clients)
• [ ] Schema published to registry with breaking change detection
• [ ] Resolver-level tracing enabled (Apollo Studio, OpenTelemetry)
• [ ] Error masking: internal errors never leak to clients in production
• [ ] Pagination uses Relay cursor-based spec (not offset)
• [ ] Input validation on all mutation arguments
• [ ] Subscription authentication verified on connection init