aigroup-workflow 2.2.0 → 2.2.2

package/skills/backend/graphql-architect/references/migration-from-rest.md

@@ -1,1141 +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/references/schema-design.md** - Type system patterns and schema structure
-- **graphql-architect/references/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
+# 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/references/schema-design.md** - Type system patterns and schema structure
+- **graphql-architect/references/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