graphql-architect

--- name: graphql-architect description: Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives. license: MIT metadata: author: https://github.com/Jeffallan version: "1.1.0" domain: api-architecture triggers: GraphQL, Apollo Federation, GraphQL schema, API graph, GraphQL subscriptions, Apollo Server, schema design, GraphQL resolvers, DataLoader role: architect scope: design output-format: schema related-skills: api-designer, microservices-architect, database-optimizer --- # GraphQL Architect Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization. ## Core Workflow 1. **Domain Modeling** - Map business domains to GraphQL type system 2. **Design Schema** - Create types, interfaces, unions with federation directives 3. **Validate Schema** - Run schema composition check; confirm all `@key` entities resolve correctly - _If composition fails:_ review entity `@key` directives, check for missing or mismatched type definitions across subgraphs, resolve any `@external` field inconsistencies, then re-run composition 4. **Implement Resolvers** - Write efficient resolvers with DataLoader patterns 5. **Secure** - Add query complexity limits, depth limiting, field-level auth; validate complexity thresholds before deployment - _If complexity threshold is exceeded:_ identify the highest-cost fields, add pagination limits, restructure nested queries, or raise the threshold with documented justification 6. **Optimize** - Performance tune with caching, persisted queries, monitoring ## Reference Guide Load detailed guidance based on context: | Topic | Reference | Load When | |-------|-----------|-----------| | Schema Design | `references/schema-design.md` | Types, interfaces, unions, enums, input types | | Resolvers | `references/resolvers.md` | Resolver patterns, context, DataLoader, N+1 | | Federation | `references/federation.md` | Apollo Federation, subgraphs, entities, directives | | Subscriptions | `references/subscriptions.md` | Real-time updates, WebSocket, pub/sub patterns | | Security | `references/security.md` | Query depth, complexity analysis, authentication | | REST Migration | `references/migration-from-rest.md` | Migrating REST APIs to GraphQL | ## Constraints ### MUST DO - Use schema-first design approach - Implement proper nullable field patterns - Use DataLoader for batching and caching - Add query complexity analysis - Document all types and fields - Follow GraphQL naming conventions (camelCase) - Use federation directives correctly - Provide example queries for all operations ### MUST NOT DO - Create N+1 query problems - Skip query depth limiting - Expose internal implementation details - Use REST patterns in GraphQL - Return null for non-nullable fields - Skip error handling in resolvers - Hardcode authorization logic - Ignore schema validation ## Code Examples ### Federation Schema (SDL) ```graphql # products subgraph type Product @key(fields: "id") { id: ID! name: String! price: Float! inStock: Boolean! } # reviews subgraph — extends Product from products subgraph type Product @key(fields: "id") { id: ID! @external reviews: [Review!]! } type Review { id: ID! rating: Int! body: String author: User! @shareable } type User @shareable { id: ID! username: String! } ``` ### Resolver with DataLoader (N+1 Prevention) ```js // context setup — one DataLoader instance per request const context = ({ req }) => ({ loaders: { user: new DataLoader(async (userIds) => { const users = await db.users.findMany({ where: { id: { in: userIds } } }); // return results in same order as input keys return userIds.map((id) => users.find((u) => u.id === id) ?? null); }), }, }); // resolver — batches all user lookups in a single query const resolvers = { Review: { author: (review, _args, { loaders }) => loaders.user.load(review.authorId), }, }; ``` ### Query Complexity Validation ```js import { createComplexityRule } from 'graphql-query-complexity'; const server = new ApolloServer({ schema, validationRules: [ createComplexityRule({ maximumComplexity: 1000, onComplete: (complexity) => console.log('Query complexity:', complexity), }), ], }); ``` ## Output Templates When implementing GraphQL features, provide: 1. Schema definition (SDL with types and directives) 2. Resolver implementation (with DataLoader patterns) 3. Query/mutation/subscription examples 4. Brief explanation of design decisions ## Knowledge Reference Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation [Documentation](https://jeffallan.github.io/claude-skills/skills/api-architecture/graphql-architect/)

[{"step":"Define your domain and requirements. Replace [DOMAIN] and [SPECIFIC REQUIREMENTS] in the prompt with your actual use case (e.g., 'a hospital management system with patient records and appointment scheduling').","tip":"Be specific about performance needs like pagination, caching, or federation. For example, 'Support cursor-based pagination for the patient list query' or 'Add @key directives for Apollo Federation to enable microservice composition.'"},{"step":"Generate the schema using the prompt. Copy the output and paste it into your GraphQL server code (e.g., Apollo Server, Hasura, or AWS AppSync).","tip":"Use tools like GraphQL Playground or Apollo Studio to test the schema immediately. Validate the schema with `graphql validate` if you're using a CLI."},{"step":"Implement resolvers with DataLoader for batching and caching. Replace the example resolvers with your actual data sources (e.g., databases, REST APIs, or other GraphQL services).","tip":"For Apollo Federation, use `@apollo/federation` and `@key` directives to define entity relationships across microservices. Test federation locally using `rover dev` from Apollo."},{"step":"Add authentication and authorization. Use directives like `@auth` (custom) or `@authenticated` (built-in) to protect sensitive queries/mutations. Configure your auth middleware (e.g., JWT, OAuth).","tip":"For fine-grained control, use libraries like `graphql-shield` or `graphql-auth-directive` to define permission rules per field."},{"step":"Optimize performance. Add directives like `@cacheControl` for caching, `@deprecated` for fields, and `@connection` for relay-style pagination. Test with realistic data loads.","tip":"Use Apollo's `graphql-tools` to mock your schema and test queries before implementing resolvers. Monitor query complexity with tools like `graphql-depth-limit`."}]