@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/graphql-architect/steering/migration-from-rest.md

@@ -0,0 +1,1141 @@
+# REST to GraphQL Migration Guide
+
+---
+
+## When to Use This Guide
+
+**Migrate to GraphQL when:**
+- Multiple round-trips required for complex UI views
+- Over-fetching or under-fetching data is problematic
+- Supporting diverse client needs (mobile, web, desktop)
+- Team boundaries require federated API architecture
+- Real-time subscriptions are core requirements
+- Type safety across client-server boundary needed
+- API versioning complexity is growing
+
+**Success indicators:**
+- Client applications make many sequential REST calls
+- Different clients need different data shapes
+- Mobile apps suffer from bandwidth constraints
+- Frontend teams wait on backend API changes
+- Multiple REST versions exist concurrently
+
+## When NOT to Use GraphQL
+
+**Stick with REST when:**
+- Simple CRUD operations with stable clients
+- File upload/download is primary use case
+- HTTP caching is critical (CDN, browser cache)
+- Team lacks GraphQL expertise and training budget
+- Existing REST API is well-designed and sufficient
+- Third-party integrations require REST endpoints
+- Query complexity would create security risks
+
+**Warning signs:**
+- Team of 1-2 developers (operational overhead)
+- Primarily server-to-server communication
+- Static content delivery is the main requirement
+- No complex data relationship navigation needed
+
+---
+
+## Concept Mapping: REST to GraphQL
+
+| REST Concept | GraphQL Equivalent | Notes |
+|--------------|-------------------|-------|
+| GET /users | Query users | Read operations |
+| GET /users/:id | Query user(id: ID!) | Single entity fetch |
+| POST /users | Mutation createUser | Create operations |
+| PUT /users/:id | Mutation updateUser | Update operations |
+| DELETE /users/:id | Mutation deleteUser | Delete operations |
+| PATCH /users/:id | Mutation updateUserPartial | Partial updates |
+| Query params (?filter=...) | Field arguments | Filtering/sorting |
+| URL path segments | Nested field selection | Data relationships |
+| Multiple endpoints | Single query | Eliminate round-trips |
+| Webhook callbacks | Subscriptions | Real-time updates |
+| HTTP status codes | Errors array + data | Partial success model |
+| API versioning | Schema evolution | Deprecation over versions |
+| /users?include=posts | users { posts } | Eager loading control |
+| Offset pagination | Cursor-based connections | Relay specification |
+| Accept header | Operation selection | Content negotiation |
+| OAuth/JWT tokens | Context authentication | Same auth patterns |
+
+---
+
+## Pattern 1: GET Endpoints to Queries
+
+### REST Endpoint
+
+```typescript
+// GET /api/users/:id
+interface UserResponse {
+  id: string;
+  name: string;
+  email: string;
+  created_at: string;
+  posts: Array<{
+    id: string;
+    title: string;
+    published: boolean;
+  }>;
+}
+
+app.get('/api/users/:id', async (req, res) => {
+  const user = await db.users.findById(req.params.id);
+  const posts = await db.posts.findByUserId(user.id); // N+1 risk
+
+  res.json({
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    created_at: user.createdAt.toISOString(),
+    posts: posts.map(p => ({
+      id: p.id,
+      title: p.title,
+      published: p.published
+    }))
+  });
+});
+```
+
+### GraphQL Schema
+
+```graphql
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  createdAt: DateTime!
+  posts: [Post!]!
+}
+
+type Post {
+  id: ID!
+  title: String!
+  published: Boolean!
+  author: User!
+}
+
+type Query {
+  user(id: ID!): User
+  users(filter: UserFilter, limit: Int = 20): [User!]!
+}
+
+input UserFilter {
+  nameContains: String
+  createdAfter: DateTime
+}
+
+scalar DateTime
+```
+
+### GraphQL Resolver with DataLoader
+
+```typescript
+import DataLoader from 'dataloader';
+import { IResolvers } from '@graphql-tools/utils';
+
+// Batch loading to prevent N+1 queries
+const createPostsByUserIdLoader = (db: Database) =>
+  new DataLoader<string, Post[]>(async (userIds) => {
+    const posts = await db.posts.findByUserIds([...userIds]);
+
+    // Group posts by userId
+    const postsByUserId = userIds.map(id =>
+      posts.filter(post => post.userId === id)
+    );
+
+    return postsByUserId;
+  });
+
+const createUserByIdLoader = (db: Database) =>
+  new DataLoader<string, User>(async (ids) => {
+    const users = await db.users.findByIds([...ids]);
+
+    // Maintain order matching input ids
+    return ids.map(id => users.find(user => user.id === id));
+  });
+
+interface Context {
+  db: Database;
+  loaders: {
+    userById: DataLoader<string, User>;
+    postsByUserId: DataLoader<string, Post[]>;
+  };
+}
+
+const resolvers: IResolvers<any, Context> = {
+  Query: {
+    user: async (_, { id }, { loaders }) => {
+      return loaders.userById.load(id);
+    },
+
+    users: async (_, { filter, limit }, { db }) => {
+      return db.users.find(filter, { limit });
+    },
+  },
+
+  User: {
+    posts: async (user, _, { loaders }) => {
+      // DataLoader batches and caches these calls
+      return loaders.postsByUserId.load(user.id);
+    },
+  },
+
+  Post: {
+    author: async (post, _, { loaders }) => {
+      return loaders.userById.load(post.userId);
+    },
+  },
+};
+
+// Apollo Server setup
+import { ApolloServer } from '@apollo/server';
+import { startStandaloneServer } from '@apollo/server/standalone';
+
+const server = new ApolloServer<Context>({
+  typeDefs,
+  resolvers,
+});
+
+const { url } = await startStandaloneServer(server, {
+  context: async ({ req }) => {
+    const db = createDatabaseConnection();
+
+    return {
+      db,
+      loaders: {
+        userById: createUserByIdLoader(db),
+        postsByUserId: createPostsByUserIdLoader(db),
+      },
+    };
+  },
+});
+```
+
+### Client Query Examples
+
+```typescript
+// Flexible field selection - client controls response shape
+const MINIMAL_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+    }
+  }
+`;
+
+const DETAILED_USER = gql`
+  query GetUserWithPosts($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      email
+      createdAt
+      posts {
+        id
+        title
+        published
+      }
+    }
+  }
+`;
+
+// Single query replacing multiple REST calls
+const DASHBOARD_DATA = gql`
+  query Dashboard($userId: ID!) {
+    user(id: $userId) {
+      name
+      posts {
+        id
+        title
+      }
+    }
+
+    # Would require separate REST endpoint
+    users(filter: { createdAfter: "2025-01-01" }, limit: 5) {
+      id
+      name
+    }
+  }
+`;
+```
+
+---
+
+## Pattern 2: POST/PUT/DELETE to Mutations
+
+### REST Endpoints
+
+```typescript
+// POST /api/users
+app.post('/api/users', async (req, res) => {
+  const { name, email, password } = req.body;
+
+  if (!name || !email) {
+    return res.status(400).json({ error: 'Missing required fields' });
+  }
+
+  const user = await db.users.create({ name, email, password });
+  res.status(201).json(user);
+});
+
+// PUT /api/users/:id
+app.put('/api/users/:id', async (req, res) => {
+  const user = await db.users.update(req.params.id, req.body);
+  res.json(user);
+});
+
+// DELETE /api/users/:id
+app.delete('/api/users/:id', async (req, res) => {
+  await db.users.delete(req.params.id);
+  res.status(204).send();
+});
+```
+
+### GraphQL Schema
+
+```graphql
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+input CreateUserInput {
+  name: String!
+  email: String!
+  password: String!
+}
+
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]!
+}
+
+input UpdateUserInput {
+  id: ID!
+  name: String
+  email: String
+}
+
+type UpdateUserPayload {
+  user: User
+  errors: [UserError!]!
+}
+
+type DeleteUserPayload {
+  deletedId: ID
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+
+enum ErrorCode {
+  VALIDATION_ERROR
+  NOT_FOUND
+  UNAUTHORIZED
+  INTERNAL_ERROR
+}
+```
+
+### GraphQL Mutation Resolvers
+
+```typescript
+const resolvers: IResolvers<any, Context> = {
+  Mutation: {
+    createUser: async (_, { input }, { db, user }) => {
+      try {
+        // Validation
+        if (!isValidEmail(input.email)) {
+          return {
+            user: null,
+            errors: [{
+              field: 'email',
+              message: 'Invalid email format',
+              code: 'VALIDATION_ERROR',
+            }],
+          };
+        }
+
+        // Check for duplicate
+        const existing = await db.users.findByEmail(input.email);
+        if (existing) {
+          return {
+            user: null,
+            errors: [{
+              field: 'email',
+              message: 'Email already registered',
+              code: 'VALIDATION_ERROR',
+            }],
+          };
+        }
+
+        const hashedPassword = await bcrypt.hash(input.password, 10);
+        const newUser = await db.users.create({
+          name: input.name,
+          email: input.email,
+          password: hashedPassword,
+        });
+
+        return {
+          user: newUser,
+          errors: [],
+        };
+      } catch (error) {
+        return {
+          user: null,
+          errors: [{
+            message: 'Failed to create user',
+            code: 'INTERNAL_ERROR',
+          }],
+        };
+      }
+    },
+
+    updateUser: async (_, { input }, { db, user }) => {
+      if (!user || user.id !== input.id) {
+        return {
+          user: null,
+          errors: [{
+            message: 'Unauthorized',
+            code: 'UNAUTHORIZED',
+          }],
+        };
+      }
+
+      const updated = await db.users.update(input.id, {
+        ...(input.name && { name: input.name }),
+        ...(input.email && { email: input.email }),
+      });
+
+      return {
+        user: updated,
+        errors: [],
+      };
+    },
+
+    deleteUser: async (_, { id }, { db, user }) => {
+      if (!user || user.id !== id) {
+        return {
+          deletedId: null,
+          errors: [{ message: 'Unauthorized', code: 'UNAUTHORIZED' }],
+        };
+      }
+
+      await db.users.delete(id);
+
+      return {
+        deletedId: id,
+        errors: [],
+      };
+    },
+  },
+};
+```
+
+### Client Mutation Examples
+
+```typescript
+const CREATE_USER = gql`
+  mutation CreateUser($input: CreateUserInput!) {
+    createUser(input: $input) {
+      user {
+        id
+        name
+        email
+        createdAt
+      }
+      errors {
+        field
+        message
+        code
+      }
+    }
+  }
+`;
+
+// Usage with error handling
+const [createUser] = useMutation(CREATE_USER);
+
+const handleSubmit = async (formData) => {
+  const { data } = await createUser({
+    variables: {
+      input: formData,
+    },
+  });
+
+  if (data.createUser.errors.length > 0) {
+    // Handle validation errors
+    data.createUser.errors.forEach(error => {
+      setFieldError(error.field, error.message);
+    });
+  } else {
+    // Success - use the returned user
+    navigate(`/users/${data.createUser.user.id}`);
+  }
+};
+```
+
+---
+
+## Pattern 3: Pagination Migration
+
+### REST Offset Pagination
+
+```typescript
+// GET /api/posts?page=2&limit=20
+app.get('/api/posts', async (req, res) => {
+  const page = parseInt(req.query.page) || 1;
+  const limit = parseInt(req.query.limit) || 20;
+  const offset = (page - 1) * limit;
+
+  const posts = await db.posts.find({
+    limit,
+    offset,
+  });
+
+  const total = await db.posts.count();
+
+  res.json({
+    data: posts,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  });
+});
+```
+
+### GraphQL Cursor-Based Pagination (Relay Connections)
+
+```graphql
+type Query {
+  posts(
+    first: Int
+    after: String
+    last: Int
+    before: String
+    filter: PostFilter
+  ): PostConnection!
+}
+
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type PostEdge {
+  node: Post!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+
+input PostFilter {
+  published: Boolean
+  authorId: ID
+  titleContains: String
+}
+```
+
+### Cursor Pagination Resolver
+
+```typescript
+import { encodeCursor, decodeCursor } from './cursor-utils';
+
+const resolvers: IResolvers = {
+  Query: {
+    posts: async (_, args, { db }) => {
+      const { first, after, last, before, filter } = args;
+
+      // Validate pagination args
+      if (first && last) {
+        throw new Error('Cannot specify both first and last');
+      }
+
+      const limit = first || last || 20;
+      const isForward = !!first || !last;
+
+      // Decode cursor to get offset
+      let offset = 0;
+      if (after) {
+        offset = decodeCursor(after) + 1;
+      } else if (before) {
+        offset = Math.max(0, decodeCursor(before) - limit);
+      }
+
+      // Fetch one extra to determine hasNextPage
+      const posts = await db.posts.find({
+        filter,
+        limit: limit + 1,
+        offset,
+        orderBy: { createdAt: isForward ? 'DESC' : 'ASC' },
+      });
+
+      const hasMore = posts.length > limit;
+      const nodes = hasMore ? posts.slice(0, limit) : posts;
+
+      if (!isForward) {
+        nodes.reverse();
+      }
+
+      const edges = nodes.map((post, index) => ({
+        node: post,
+        cursor: encodeCursor(offset + index),
+      }));
+
+      const totalCount = await db.posts.count(filter);
+
+      return {
+        edges,
+        pageInfo: {
+          hasNextPage: isForward ? hasMore : offset > 0,
+          hasPreviousPage: !isForward ? hasMore : offset > 0,
+          startCursor: edges[0]?.cursor,
+          endCursor: edges[edges.length - 1]?.cursor,
+        },
+        totalCount,
+      };
+    },
+  },
+};
+
+// cursor-utils.ts
+export const encodeCursor = (offset: number): string => {
+  return Buffer.from(`cursor:${offset}`).toString('base64');
+};
+
+export const decodeCursor = (cursor: string): number => {
+  const decoded = Buffer.from(cursor, 'base64').toString('utf-8');
+  return parseInt(decoded.replace('cursor:', ''));
+};
+```
+
+### Client Pagination Query
+
+```typescript
+const POSTS_QUERY = gql`
+  query Posts($first: Int!, $after: String, $filter: PostFilter) {
+    posts(first: $first, after: $after, filter: $filter) {
+      edges {
+        node {
+          id
+          title
+          published
+          author {
+            name
+          }
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+`;
+
+// Infinite scroll implementation
+const PostList = () => {
+  const { data, loading, fetchMore } = useQuery(POSTS_QUERY, {
+    variables: { first: 20 },
+  });
+
+  const loadMore = () => {
+    fetchMore({
+      variables: {
+        after: data.posts.pageInfo.endCursor,
+      },
+      updateQuery: (prev, { fetchMoreResult }) => {
+        if (!fetchMoreResult) return prev;
+
+        return {
+          posts: {
+            ...fetchMoreResult.posts,
+            edges: [
+              ...prev.posts.edges,
+              ...fetchMoreResult.posts.edges,
+            ],
+          },
+        };
+      },
+    });
+  };
+
+  return (
+    <div>
+      {data?.posts.edges.map(({ node }) => (
+        <PostCard key={node.id} post={node} />
+      ))}
+
+      {data?.posts.pageInfo.hasNextPage && (
+        <button onClick={loadMore}>Load More</button>
+      )}
+    </div>
+  );
+};
+```
+
+---
+
+## Pattern 4: Authentication Translation
+
+### REST Authentication
+
+```typescript
+// REST middleware
+app.use(async (req, res, next) => {
+  const token = req.headers.authorization?.replace('Bearer ', '');
+
+  if (token) {
+    try {
+      const payload = jwt.verify(token, process.env.JWT_SECRET);
+      req.user = await db.users.findById(payload.userId);
+    } catch (error) {
+      return res.status(401).json({ error: 'Invalid token' });
+    }
+  }
+
+  next();
+});
+```
+
+### GraphQL Authentication Context
+
+```typescript
+import { ApolloServer } from '@apollo/server';
+import { GraphQLError } from 'graphql';
+
+interface AuthContext {
+  user: User | null;
+  requireAuth: () => User;
+}
+
+const server = new ApolloServer<AuthContext>({
+  typeDefs,
+  resolvers,
+});
+
+await startStandaloneServer(server, {
+  context: async ({ req }) => {
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    let user: User | null = null;
+
+    if (token) {
+      try {
+        const payload = jwt.verify(token, process.env.JWT_SECRET);
+        user = await db.users.findById(payload.userId);
+      } catch (error) {
+        // Token invalid - continue with user = null
+      }
+    }
+
+    return {
+      user,
+      db,
+      loaders: createLoaders(db),
+
+      // Helper to enforce authentication
+      requireAuth: (): User => {
+        if (!user) {
+          throw new GraphQLError('Authentication required', {
+            extensions: { code: 'UNAUTHENTICATED' },
+          });
+        }
+        return user;
+      },
+    };
+  },
+});
+```
+
+### Field-Level Authorization
+
+```typescript
+import { GraphQLFieldResolver } from 'graphql';
+
+// Authorization directive
+const resolvers: IResolvers = {
+  Query: {
+    me: (_, __, { requireAuth }) => {
+      const user = requireAuth();
+      return user;
+    },
+
+    users: (_, __, { user }) => {
+      // Optional auth - different data based on auth state
+      if (user?.role === 'ADMIN') {
+        return db.users.findAll();
+      }
+
+      // Public view - limited fields
+      return db.users.findPublic();
+    },
+  },
+
+  User: {
+    email: (user, _, { user: currentUser }) => {
+      // Field-level privacy
+      if (currentUser?.id === user.id || currentUser?.role === 'ADMIN') {
+        return user.email;
+      }
+      return null;
+    },
+  },
+};
+```
+
+---
+
+## BFF (Backend for Frontend) Architecture
+
+### Multi-Client GraphQL Gateway
+
+```typescript
+// Schema stitching for different clients
+import { stitchSchemas } from '@graphql-tools/stitch';
+
+// Mobile-optimized schema
+const mobileSchema = makeExecutableSchema({
+  typeDefs: `
+    type Query {
+      # Denormalized for fewer round-trips
+      dashboard: MobileDashboard!
+    }
+
+    type MobileDashboard {
+      user: User!
+      recentPosts: [Post!]!
+      notifications: [Notification!]!
+      # All data needed for mobile home screen
+    }
+  `,
+  resolvers: mobileResolvers,
+});
+
+// Web-optimized schema
+const webSchema = makeExecutableSchema({
+  typeDefs: `
+    type Query {
+      # Granular for efficient caching
+      user(id: ID!): User
+      posts(filter: PostFilter): PostConnection!
+      notifications(unreadOnly: Boolean): [Notification!]!
+    }
+  `,
+  resolvers: webResolvers,
+});
+
+// Client-specific servers
+const mobileServer = new ApolloServer({
+  schema: mobileSchema,
+  introspection: true,
+});
+
+const webServer = new ApolloServer({
+  schema: webSchema,
+  introspection: true,
+});
+
+// Route based on client header
+app.use('/graphql', (req, res) => {
+  const client = req.headers['x-client-type'];
+
+  if (client === 'mobile') {
+    return mobileServer.handleRequest(req, res);
+  }
+
+  return webServer.handleRequest(req, res);
+});
+```
+
+---
+
+## Incremental Migration Strategy
+
+### Phase 1: GraphQL Wrapper (Weeks 1-2)
+
+```typescript
+// Wrap existing REST endpoints with GraphQL
+const resolvers: IResolvers = {
+  Query: {
+    user: async (_, { id }) => {
+      // Call existing REST API internally
+      const response = await fetch(`http://localhost:3000/api/users/${id}`);
+      return response.json();
+    },
+  },
+};
+
+// Allows GraphQL adoption without backend rewrites
+// Clients can start using GraphQL immediately
+```
+
+### Phase 2: Parallel Implementation (Weeks 3-6)
+
+```typescript
+// Implement GraphQL resolvers with direct DB access
+// Keep REST endpoints running
+const resolvers: IResolvers = {
+  Query: {
+    user: async (_, { id }, { db }) => {
+      // New implementation - direct database
+      return db.users.findById(id);
+    },
+  },
+};
+
+// Feature flag to route traffic
+const USE_GRAPHQL = process.env.GRAPHQL_ENABLED === 'true';
+
+app.get('/api/users/:id', async (req, res) => {
+  if (USE_GRAPHQL) {
+    // Forward to GraphQL
+    const result = await graphqlServer.executeOperation({
+      query: `query GetUser($id: ID!) { user(id: $id) { ... } }`,
+      variables: { id: req.params.id },
+    });
+    return res.json(result.data?.user);
+  }
+
+  // Legacy REST implementation
+  const user = await db.users.findById(req.params.id);
+  res.json(user);
+});
+```
+
+### Phase 3: Client Migration (Weeks 7-12)
+
+```typescript
+// Gradual client migration with monitoring
+import { setContext } from '@apollo/client/link/context';
+
+const migrationLink = setContext((_, { headers }) => {
+  return {
+    headers: {
+      ...headers,
+      'x-graphql-migration': 'phase-3',
+    },
+  };
+});
+
+// A/B test GraphQL vs REST in production
+// Monitor performance, errors, client satisfaction
+```
+
+### Phase 4: REST Deprecation (Week 13+)
+
+```typescript
+// Deprecate REST endpoints gradually
+app.get('/api/users/:id', (req, res) => {
+  res.status(410).json({
+    error: 'This endpoint is deprecated',
+    message: 'Please use GraphQL endpoint at /graphql',
+    migrationGuide: 'https://docs.example.com/graphql-migration',
+    sunsetDate: '2025-06-01',
+  });
+});
+
+// Eventually remove REST entirely
+```
+
+---
+
+## Common Pitfalls
+
+### Pitfall 1: N+1 Query Problem
+
+```typescript
+// BAD - Causes N+1 queries
+const resolvers = {
+  User: {
+    posts: async (user, _, { db }) => {
+      // Called once per user - N queries if you fetch N users
+      return db.posts.findByUserId(user.id);
+    },
+  },
+};
+
+// GOOD - Use DataLoader
+const resolvers = {
+  User: {
+    posts: async (user, _, { loaders }) => {
+      // Batched and cached
+      return loaders.postsByUserId.load(user.id);
+    },
+  },
+};
+```
+
+### Pitfall 2: Exposing Database Schema Directly
+
+```typescript
+// BAD - Tightly coupled to database
+type User {
+  user_id: Int!          # Database column name
+  first_name: String     # Database structure leaks
+  last_name: String
+  created_at: String     # Raw DB type
+}
+
+// GOOD - API-first design
+type User {
+  id: ID!                # Abstract identifier
+  name: String!          # Computed from first + last
+  createdAt: DateTime!   # Proper type
+}
+```
+
+### Pitfall 3: Missing Error Handling
+
+```typescript
+// BAD - Errors kill entire response
+const resolvers = {
+  Query: {
+    dashboard: async () => {
+      const user = await fetchUser();     // Throws on error
+      const posts = await fetchPosts();   // Never reached if user fails
+      return { user, posts };
+    },
+  },
+};
+
+// GOOD - Partial success model
+const resolvers = {
+  Query: {
+    dashboard: async () => {
+      return {};  // Return empty object
+    },
+  },
+
+  Dashboard: {
+    user: async (_, __, context) => {
+      try {
+        return await fetchUser();
+      } catch (error) {
+        return null;  // Client still gets posts
+      }
+    },
+
+    posts: async () => {
+      try {
+        return await fetchPosts();
+      } catch (error) {
+        return [];  // Graceful degradation
+      }
+    },
+  },
+};
+```
+
+### Pitfall 4: Ignoring Query Complexity
+
+```typescript
+// BAD - No limits on query depth/complexity
+// Client can write expensive queries that DOS the server
+
+// GOOD - Implement complexity limits
+import { createComplexityLimitRule } from 'graphql-validation-complexity';
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [
+    createComplexityLimitRule(1000, {
+      onCost: (cost) => {
+        console.log('Query cost:', cost);
+      },
+    }),
+  ],
+});
+
+// Assign costs to fields
+const typeDefs = `
+  type Query {
+    users: [User!]! @cost(complexity: 10)
+    user(id: ID!): User @cost(complexity: 1)
+  }
+
+  type User {
+    posts: [Post!]! @cost(complexity: 5, multipliers: ["first"])
+  }
+`;
+```
+
+### Pitfall 5: Over-Normalization
+
+```typescript
+// BAD - Too granular, requires many queries
+type Query {
+  userName(id: ID!): String
+  userEmail(id: ID!): String
+  userPosts(userId: ID!): [Post!]!
+}
+
+// GOOD - Logical grouping
+type Query {
+  user(id: ID!): User
+}
+
+type User {
+  name: String!
+  email: String!
+  posts: [Post!]!
+}
+```
+
+---
+
+## Cross-References
+
+**Related Skills:**
+- **graphql-architect/steering/schema-design.md** - Type system patterns and schema structure
+- **graphql-architect/steering/federation-guide.md** - Multi-service GraphQL architecture
+- **backend-developer** - REST API implementation patterns
+- **api-designer** - API design principles and consistency
+
+**When to Escalate:**
+- Federation across microservices → See federation-guide.md
+- Schema design questions → See schema-design.md
+- Complex subscription requirements → Consult graphql-architect
+- Performance optimization → Partner with performance-engineer
+
+---
+
+## Migration Checklist
+
+- [ ] Identify most-used REST endpoints
+- [ ] Map REST resources to GraphQL types
+- [ ] Design schema following best practices
+- [ ] Implement DataLoaders for all relations
+- [ ] Add authentication/authorization
+- [ ] Implement pagination (cursor-based)
+- [ ] Set up query complexity limits
+- [ ] Create client migration plan
+- [ ] Monitor performance metrics
+- [ ] Document GraphQL queries for clients
+- [ ] Train team on GraphQL patterns
+- [ ] Plan REST endpoint sunset timeline
+
+**Migration complete when:**
+- All critical paths use GraphQL
+- REST endpoints deprecated with sunset dates
+- Client applications fully migrated
+- Performance metrics meet or exceed REST baseline
+- Team confident in GraphQL maintenance