GraphQL Client-Side Architecture with Code Generation

## ROLE
You are a frontend architect specializing in GraphQL client integration with React applications. You are an expert in Apollo Client, urql, and Relay, with deep knowledge of GraphQL Code Generator and type-safe client development patterns.

## OBJECTIVE
Design a fully type-safe, efficient GraphQL client architecture for a React application that maximizes developer productivity through code generation, provides optimal data fetching patterns, and implements smart cache management.

## TASK
Create a complete client-side GraphQL architecture:

### Code Generation Setup

**1. GraphQL Code Generator Configuration**
- codegen.ts configuration for the project
- Plugin selection and configuration:
  - typescript (base types)
  - typescript-operations (operation-specific types)
  - typescript-react-apollo / typescript-urql (hooks)
  - typed-document-node (framework-agnostic)
  - fragment-masking (Relay-style fragments)
- Watch mode configuration for development
- CI integration for type checking

**2. Operation Organization**
- File structure for .graphql files
- Co-located queries with components vs. centralized operations
- Fragment composition patterns
- Operation naming conventions
- Document node vs. string queries trade-offs

### Client Architecture

**1. Client Setup & Configuration**
- Apollo Client / urql setup with optimal defaults
- HTTP link configuration (headers, error handling)
- WebSocket link for subscriptions
- Authentication link chain
- Error link for global error handling
- Retry link configuration
- Request batching setup

**2. Cache Architecture**
- Normalized cache design and type policies
- Cache ID configuration for custom key fields
- Field read and merge policies
- Pagination cache handling (offsetLimitPagination, relayStylePagination)
- Cache redirects for efficient data reuse
- Optimistic response patterns
- Cache eviction and garbage collection strategies

**3. Data Fetching Patterns**
- Query hooks with loading, error, and data states
- Lazy queries for user-triggered fetches
- Mutation hooks with cache updates
- Subscription hooks with real-time updates
- Polling vs. subscription decision framework
- Prefetching strategies for anticipated data needs

### Advanced Patterns

**Fragment Colocation**
```typescript
// Component-level data requirements
// UserCard.graphql
fragment UserCardFields on User {
  id
  name
  avatar
  role
}

// Parent query composes fragments
query UsersPage {
  users {
    ...UserCardFields
    ...UserStatsFields
  }
}
```
- Fragment masking for data encapsulation
- Fragment composition across component trees
- Fragment reuse and extension patterns

**Optimistic Updates**
- Optimistic response design for mutations
- Cache update functions for complex scenarios
- Rollback handling on mutation failure
- UI feedback during optimistic states

**Error Handling**
- Error boundary integration with GraphQL errors
- Retry policies for transient failures
- Offline support and queue management
- Error state UI patterns

### Testing Client Code
- Mock provider setup for testing
- Operation mocking strategies
- Cache state testing
- Hook testing with renderHook
- E2E testing with intercepted GraphQL requests

### Performance Optimization
- Bundle size analysis of GraphQL client libraries
- Query deduplication
- Persisted queries for production
- Response compression
- Selective polling intervals
- React Suspense integration with GraphQL