A production GraphQL server is usually more than a schema and a few resolver functions. A clean architecture separates concerns between transport, GraphQL execution, application services, data access, and infrastructure.

A useful structure is:

HTTP / WebSocket Transport
          ↓
GraphQL Server
          ↓
Schema + Validation
          ↓
Resolvers
          ↓
Application Services
          ↓
Repositories / Data Sources
          ↓
Database / External APIs

For a Node.js application, a possible project structure is:

src/
  graphql/
    schema/
    resolvers/
  services/
  repositories/
  models/
  middleware/
  context/
  config/
  server.js

The exact structure is not mandatory. The important principle is separation of responsibilities.

GraphQL layer

Defines the API contract and coordinates execution.

Service layer

Contains application and business logic.

Repository/data-access layer

Handles persistence and external data access.

Infrastructure layer

Handles database connections, logging, configuration, queues, and other operational concerns.

Keeping these boundaries clear prevents resolver files from becoming large collections of database queries and business rules.

A Node.js GraphQL project needs a runtime, a GraphQL implementation, and a server integration.

One popular approach is to use Apollo Server with Node.js. The exact package versions and setup details can evolve, but the architectural concepts remain the same.

A minimal application conceptually needs:

Node.js
  +
GraphQL implementation
  +
GraphQL server framework
  +
Schema
  +
Resolvers

A simple project might contain:

graphql-app/
  package.json
  src/
    schema.js
    resolvers.js
    server.js

The server entry point creates the GraphQL server, registers the schema and resolvers, and starts the HTTP server.

A minimal schema could be:

type Query {
  hello: String!
}

and the resolver:

const resolvers = {
  Query: {
    hello: () => "Hello, GraphQL!"
  }
};

The important learning objective at this stage is not memorizing a particular framework API. It is understanding the relationship between schema, resolver, server, and client operation.

GraphQL context is commonly used to expose request-scoped dependencies to resolvers.

For example, a request context might contain:

{
  user: authenticatedUser,
  requestId: "req-123",
  userService,
  postService,
  loaders
}

A resolver can then access those values:

const resolvers = {
  Query: {
    me: (_, __, context) => {
      return context.user;
    }
  }
};

Context is especially useful for authentication because authentication middleware can establish the current user before GraphQL execution begins.

It can also hold request-specific DataLoader instances. This is important because DataLoader caches should normally be scoped appropriately to a request rather than accidentally shared across unrelated users.

Avoid putting global mutable state into context simply because context is convenient. Application-wide configuration, immutable service instances, and request-specific information have different lifecycles and should be modeled accordingly.

A clean context design makes dependencies explicit and reduces the temptation to import global mutable variables from everywhere in the resolver layer.

GraphQL errors are different from traditional REST error handling because a response can contain both data and errors.

For example:

{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "User not found"
    }
  ]
}

The exact result depends on the field's nullability and the execution failure.

GraphQL errors can originate from validation, parsing, variable coercion, resolver execution, authorization, or other layers.

Consider:

type Query {
  user(id: ID!): User
}

Because user is nullable, an execution failure can result in user: null alongside an error.

Now consider:

type Query {
  user(id: ID!): User!
}

The non-null contract changes error propagation. If the resolver cannot produce a valid non-null user, GraphQL can propagate null to a nullable parent field, potentially causing a larger portion of the response to become null.

Production APIs should also avoid leaking sensitive internal information through error messages. Database stack traces, credentials, internal hostnames, and implementation details should not become client-facing errors.

A consistent error classification strategy helps clients distinguish expected business failures from unexpected infrastructure failures.

As a GraphQL application grows, placing everything in one schema file and one resolver file becomes difficult to maintain.

A modular structure can organize GraphQL capabilities by domain:

src/
  modules/
    users/
      user.schema.js
      user.resolvers.js
      user.service.js
      user.repository.js
    products/
      product.schema.js
      product.resolvers.js
      product.service.js
      product.repository.js
  graphql/
    schema.js
    context.js
  infrastructure/
    database.js
    cache.js
  server.js

The exact naming convention is less important than the ownership boundaries.

A users module can own user-related schema definitions, resolvers, services, and repositories. A products module can do the same for products.

The root GraphQL schema can then compose these domain definitions.

This modular approach becomes increasingly valuable when the application has multiple teams, because ownership and change boundaries become clearer.

However, modularity should not mean creating hundreds of tiny files without meaningful boundaries. A module should represent a cohesive domain or capability rather than an arbitrary number of functions.