GraphQL Schema Architect

Design efficient GraphQL schemas with proper type definitions, queries, mutations, subscriptions, and resolvers.

**Application Domain:** [E-COMMERCE / SOCIAL NETWORK / CONTENT PLATFORM / HEALTHCARE / FINANCIAL SERVICES]
**Scale Expectation:** [SMALL (<10K users) / MEDIUM (10K-100K) / LARGE (>100K)]

**Schema Components to Design:**

**Type Definitions:**
- Object types with field descriptions and deprecation annotations
- Input types for mutations with validation rules
- Enum types for fixed sets of values (status, role, category)
- Union types for polymorphic fields (SearchResult = User | Post | Comment)
- Interface types for shared fields across different types
- Scalar custom types (DateTime, ISODate, Currency, Upload for file uploads)

**Query Design:**
- Root query type with filtered, paginated list queries
- Single resource queries with ID and optional slug/UUID lookup
- Nested field selection optimization (avoid N+1 by design)
- Query complexity analysis and depth limiting recommendations
- Field-level authorization annotations

**Mutation Design:**
- Create mutations with input types and validation errors
- Update mutations with partial update support
- Delete mutations with soft delete vs. hard delete options
- Bulk mutation operations for batch processing
- Mutation return types with success/error union patterns
- Idempotency key support for critical mutations

**Subscription Design:**
- Real-time event types (newMessage, postUpdated, userOnline)
- Subscription filtering by resource ID or user role
- Connection type implementation for cursor-based real-time pagination
- Reconnection handling and subscription lifecycle management

**Pagination Patterns:**
- Cursor-based pagination with PageInfo type (before/after/hasNextPage/hasPreviousPage)
- Relay-style connection pattern with edges and node typing
- Offset-based pagination alternative for simpler use cases
- Total count optimization (cached vs. computed)

**Error Handling Conventions:**
- Standardized error response format (message, code, field, details)
- GraphQL errors vs. HTTP status codes mapping
- Validation error aggregation with field-level error messages
- Custom error types for domain-specific errors (NotFoundError, UnauthorizedError, ConflictError)

**Performance Optimization:**
- DataLoader pattern implementation to prevent N+1 queries
- Query depth limiting configuration recommendations
- Response caching strategy (HTTP cache headers, CDN integration)
- Field-level authorization with resolver middleware
- Batch mutation support for reducing round trips

**Schema Federation (Microservices):**
- Subgraph design with entity sharing across services
- Key field definitions for entity resolution
- Custom directive usage (@auth, @cacheControl, @cost)
- Gateway configuration recommendations

How to Customize It

Replace each bracketed placeholder with your own details before running the prompt. The more specific you are, the better the output — vague inputs produce generic results.

• [E-COMMERCE / SOCIAL NETWORK / CONTENT PLATFORM / HEALTHCARE / FINANCIAL SERVICES]Swap in your e-commerce or social network or content platform or healthcare or financial services.
• [SMALL (<10K users) / MEDIUM (10K-100K) / LARGE (>100K)]Swap in your small (<10k users) or medium (10k-100k) or large (>100k).

When to Use It

• Standing up a GraphQL API over existing services and needing the schema to be right before clients depend on it.
• Fixing a GraphQL server whose resolvers are hammering the database — the N+1 sections apply retroactively.
• Evaluating GraphQL against REST for a specific product by seeing what the schema would actually look like.

Tips for Better Results

• 1List which clients consume the API and what screens they render — schemas designed from UI needs beat schemas mirroring database tables.
• 2Ask for the Relay-style connection spec for pagination even if you don't use Relay; retrofitting pagination onto list fields is painful.
• 3Mutations deserve their own pass: input types, error unions, and optimistic-update payloads are where schema quality shows.