GraphQL Schema Design for Web Applications

We design GraphQL schemas that serve for years without workarounds. A bad schema leads to broken N+1 queries, ghost fields, and type UserOrError instead of proper error handling. Our approach: first analyze interface needs, then define types. Experience shows: a well-designed schema reduces frontend development time by 30% and eliminates 90% of query performance issues. Team resource savings can reach 40% during the integration phase.

The schema is product-oriented, not storage-oriented. REST endpoints often mirror the database structure. With GraphQL, it's the opposite: first determine what the UI needs, then design types. This cuts rework time by half compared to traditional REST. By ordering schema design from us, you get a ready-made contract for frontend and backend. We guarantee your team won't face inconsistent interfaces.

Nodes and Edges via Relay specification. If the project is medium-sized or larger, it's worth adopting a Relay-compatible structure upfront—it sets a standard for pagination and global IDs. Typically, this saves 30% of time on interface agreement within the team.

How to Avoid N+1 in GraphQL Schema?

Every field can trigger a separate database query. Without aggregation, you get the N+1 problem. The solution is DataLoader: it batches requests by keys. Also use @cacheControl for caching at the field level. In practice, this reduces database load by 3–5 times. For example, fetching 100 orders with nested items without DataLoader generates 101 queries; with batching, only 3-4.

Why We Use Relay Specification?

Relay provides a standard for pagination (cursor-based), global IDs, and refetching. This reduces discussions within the team and makes the schema predictable. Compare: cursor pagination works 10 times faster than offset-based when fetching beyond 1000 records, as it doesn't scan the entire result set.

Basic Types and Pagination

type Query {
  node(id: ID!): Node
  product(id: ID!): Product
  products(filter: ProductFilter, page: PaginationInput): ProductConnection!
  viewer: User
}

interface Node {
  id: ID!
}

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ProductEdge {
  node: Product!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

input PaginationInput {
  first: Int
  after: String
  last: Int
  before: String
}

input ProductFilter {
  categoryIds: [ID!]
  priceMin: Decimal
  priceMax: Decimal
  inStock: Boolean
  search: String
  tags: [String!]
}

Comparison of Cursor vs. Offset Pagination

Payload Pattern for Mutations

Never return a bare object type from a mutation. Use a payload wrapper containing the result and an array of userErrors.

type CreateOrderPayload {
  order: Order
  userErrors: [UserError!]!
}

type UserError {
  field: [String!]
  message: String!
  code: OrderErrorCode
}

enum OrderErrorCode {
  INSUFFICIENT_STOCK
  INVALID_ADDRESS
  PAYMENT_DECLINED
  PRODUCT_UNAVAILABLE
}

The difference between userErrors and GraphQL errors: userErrors are predictable business errors that the client must handle. GraphQL errors are unexpected situations (exceptions, network errors).

Directives for Access Control and Caching

directive @auth(requires: Role = USER) on FIELD_DEFINITION
directive @rateLimit(max: Int!, window: String!) on FIELD_DEFINITION
directive @cacheControl(maxAge: Int, scope: CacheControlScope) on FIELD_DEFINITION | OBJECT

enum Role {
  ADMIN
  MANAGER
  USER
  GUEST
}

enum CacheControlScope {
  PUBLIC
  PRIVATE
}

# Example usage
type Query {
  products: ProductConnection! @cacheControl(maxAge: 300, scope: PUBLIC)
  dashboard: DashboardStats! @auth(requires: MANAGER) @rateLimit(max: 60, window: "1m")
}

Versioning and Deprecation

GraphQL is not versioned via URL. Instead, use continuous evolution: new fields are added, old ones are marked @deprecated. This allows clients to migrate without breaking changes. According to the GraphQL specification, this approach is considered best practice.

type Product {
  id: ID!
  name: String!
  price: Decimal @deprecated(reason: "Use `pricing.basePrice` instead")
  pricing: ProductPricing!
  variants: [ProductVariant!]!
}

type ProductPricing {
  basePrice: Decimal!
  salePrice: Decimal
  currency: CurrencyCode!
}

How to Audit an Existing Schema in 3 Steps

1. Field cartography. Collect all fields used by the client using tools like graphql-inspector. Cut off unused ones.
2. Performance profiling. Measure TTFB of each request with Apollo Studio or Sentry. Identify N+1 queries.
3. Optimization. Implement DataLoader for critical fields, add caching via @cacheControl. Reduce the number of joins.

schema/ base.graphql products.graphql orders.graphql users.graphql scalars.graphql directives.graphql 

Schema Splitting by Domains

For large projects, the schema is split into files by domain as shown above. This simplifies maintenance and review. In practice, this approach reduces merge conflict rate by 70%.

What's Included in Turnkey Schema Design

Also includes team training on schema usage and one month of post-launch support. Get a consultation — let's discuss your project.

Timelines

Schema design for a medium-sized application (5-10 entities): 3–5 days. With review, documentation, and agreement: 1 week. Contact us to discuss your project — we'll estimate the scope and propose an optimal solution. Order turnkey schema design and get rid of N+1 problems and inconsistent interfaces. Our team has 5+ years of experience and has successfully completed over 100 projects across various domains.

GraphQL is not just a technology but a discipline of contract design. We guarantee the result will meet the specification and your team's expectations.