graphql-architect

GraphQL Architect

Design GraphQL APIs that are explicit, stable, and performant.

Use This Skill For

• New GraphQL schemas or modules
• Resolver and mutation design
• Pagination, filtering, and search
• N+1 reduction and batching
• Authorization, validation, and error-shaping for GraphQL

Workflow

1. Read the Existing GraphQL Shape

• Inspect schema files, resolver structure, and context setup
• Find at least 3 existing resolver or schema patterns before adding new ones
• Match the dominant conventions for naming, nullability, and error handling

2. Design the Contract Before Implementation

• Start from client use cases, not database tables
• Define the schema shape first: queries, mutations, input types, output types
• Keep types stable and explicit; avoid ambiguous fields or overloaded mutations

3. Implement Resolver Boundaries Cleanly

• Keep resolvers thin; push business logic into services
• Validate inputs at the API boundary
• Enforce authorization close to the entry point
• Avoid leaking database details directly into schema types

4. Control Performance Early

• Use batching/data loaders where related fields fan out
• Prefer cursor pagination over ad hoc offset pagination for large lists
• Avoid fields that trigger hidden expensive work without clear client intent
• Measure N+1 risk any time a list returns nested entities

5. Verify Client Ergonomics

• Field names should describe domain concepts, not storage details
• Nullability must reflect real guarantees
• Mutation results should return enough data for immediate UI updates
• Errors should be consistent and actionable

Core Rules

• Queries read; mutations change state
• Input types and output types should be distinct
• Keep mutation names verb-first and specific
• Prefer explicit enums over magic strings
• Add deprecation before removal when evolving schemas

Common Pitfalls

• Catch-all mutations like updateThing
• Returning giant nested objects by default
• Resolver logic that talks directly to the database and the network in one layer
• Hiding authorization failures behind nulls without a deliberate contract
• Adding fields without thinking through cache keys or client churn

Output

When using this skill, produce:

• Proposed schema/resolver changes
• Notes on performance and authorization implications
• Any migration or client-impact risks