# graphql-go/graphql architecture

> Architecture diagram of the GitHub repository graphql-go/graphql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/graphql-go/graphql
- Repository: https://github.com/graphql-go/graphql

## Overview

This repository is a Go GraphQL implementation. A client submits an operation through `graphql.Do`; the library parses it into an AST, validates it against a schema, executes the requested query or mutation, and returns data and errors. Subscriptions are a separate supported operation mode. The graph also includes schema introspection and the language tooling surrounding parsing. Some source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`graphql.go`](https://github.com/graphql-go/graphql/blob/master/graphql.go) (Do entry point), [`schema.go`](https://github.com/graphql-go/graphql/blob/master/schema.go) (Schema), [`language/parser/parser.go`](https://github.com/graphql-go/graphql/blob/master/language/parser/parser.go) (Parser), [`validator.go`](https://github.com/graphql-go/graphql/blob/master/validator.go) (Document validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["GraphQL API"]
  node_request["Operation request<br/>[graphql.go]"]
  node_api_entry["Do entry point<br/>[graphql.go]"]
  node_result["Execution result<br/>[graphql.go]"]
  node_errors["GraphQL errors<br/>[error.go]"]
end

subgraph group_language["Language Processing"]
  node_parser["Parser<br/>[parser.go]"]
  node_lexer["Lexer<br/>[lexer.go]"]
  node_source["Source text<br/>[source.go]"]
  node_ast["GraphQL AST"]
end

subgraph group_execution["Schema And Execution"]
  node_schema["Schema<br/>[schema.go]"]
  node_types["GraphQL types<br/>[types.go]"]
  node_validator["Document validation<br/>[validator.go]"]
  node_rules["Validation rules<br/>[rules.go]"]
  node_executor["Operation executor<br/>[executor.go]"]
  node_plan["Execution planning<br/>[plan.go]"]
  node_values["Input and output values<br/>[values.go]"]
  node_subscriptions["Subscriptions<br/>[subscription.go]"]
  node_introspection["Introspection<br/>[introspection.go]"]
end

subgraph group_tooling["Language Tooling"]
  node_visitor["AST visitor<br/>[visitor.go]"]
  node_type_info["AST type info<br/>[type_info.go]"]
  node_printer["AST printer<br/>[printer.go]"]
end

node_client(("GraphQL client"))

node_client -->|"submits"| node_request
node_request -->|"provides input"| node_api_entry
node_api_entry -->|"parses operation"| node_parser
node_parser -->|"reads text"| node_source
node_parser -->|"requests tokens"| node_lexer
node_lexer -->|"scans text"| node_source
node_parser -->|"builds AST"| node_ast
node_api_entry -->|"validates operation"| node_validator
node_validator -->|"applies rules"| node_rules
node_validator -->|"checks against"| node_schema
node_api_entry -->|"executes operation"| node_executor
node_executor -->|"resolves against"| node_schema
node_executor -->|"plans execution"| node_plan
node_executor -->|"coerces values"| node_values
node_api_entry -->|"dispatches subscription"| node_subscriptions
node_subscriptions -->|"uses schema"| node_schema
node_schema -->|"contains type definitions"| node_types
node_schema -->|"provides introspection"| node_introspection
node_api_entry -->|"reports errors"| node_errors
node_validator -->|"traverses AST"| node_visitor
node_rules -->|"defines visitors"| node_visitor
node_visitor -->|"maintains type context"| node_type_info
node_printer -->|"prints AST nodes"| node_visitor
node_api_entry -->|"returns result"| node_result
node_result -->|"delivers data"| node_client

click node_request "https://github.com/graphql-go/graphql/blob/master/graphql.go"
click node_api_entry "https://github.com/graphql-go/graphql/blob/master/graphql.go"
click node_result "https://github.com/graphql-go/graphql/blob/master/graphql.go"
click node_parser "https://github.com/graphql-go/graphql/blob/master/language/parser/parser.go"
click node_lexer "https://github.com/graphql-go/graphql/blob/master/language/lexer/lexer.go"
click node_source "https://github.com/graphql-go/graphql/blob/master/language/source/source.go"
click node_ast "https://github.com/graphql-go/graphql/tree/master/language/ast"
click node_schema "https://github.com/graphql-go/graphql/blob/master/schema.go"
click node_types "https://github.com/graphql-go/graphql/blob/master/types.go"
click node_validator "https://github.com/graphql-go/graphql/blob/master/validator.go"
click node_rules "https://github.com/graphql-go/graphql/blob/master/rules.go"
click node_executor "https://github.com/graphql-go/graphql/blob/master/executor.go"
click node_plan "https://github.com/graphql-go/graphql/blob/master/plan.go"
click node_values "https://github.com/graphql-go/graphql/blob/master/values.go"
click node_subscriptions "https://github.com/graphql-go/graphql/blob/master/subscription.go"
click node_introspection "https://github.com/graphql-go/graphql/blob/master/introspection.go"
click node_errors "https://github.com/graphql-go/graphql/blob/master/gqlerrors/error.go"
click node_visitor "https://github.com/graphql-go/graphql/blob/master/language/visitor/visitor.go"
click node_type_info "https://github.com/graphql-go/graphql/blob/master/language/typeInfo/type_info.go"
click node_printer "https://github.com/graphql-go/graphql/blob/master/language/printer/printer.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_request,node_api_entry,node_result,node_errors,node_client toneBlue
class node_parser,node_lexer,node_source,node_ast toneAmber
class node_schema,node_types,node_validator,node_rules,node_executor,node_plan,node_values,node_subscriptions,node_introspection toneMint
class node_visitor,node_type_info,node_printer toneRose
```

## Components

### GraphQL API

- [Operation request](https://github.com/graphql-go/graphql/blob/master/graphql.go): `graphql.go`
- [Do entry point](https://github.com/graphql-go/graphql/blob/master/graphql.go): `graphql.go`
- [Execution result](https://github.com/graphql-go/graphql/blob/master/graphql.go): `graphql.go`
- [GraphQL errors](https://github.com/graphql-go/graphql/blob/master/gqlerrors/error.go): `gqlerrors/error.go`

### Language Processing

- [Parser](https://github.com/graphql-go/graphql/blob/master/language/parser/parser.go): `language/parser/parser.go`
- [Lexer](https://github.com/graphql-go/graphql/blob/master/language/lexer/lexer.go): `language/lexer/lexer.go`
- [Source text](https://github.com/graphql-go/graphql/blob/master/language/source/source.go): `language/source/source.go`
- [GraphQL AST](https://github.com/graphql-go/graphql/tree/master/language/ast): `language/ast`

### Schema And Execution

- [Schema](https://github.com/graphql-go/graphql/blob/master/schema.go): `schema.go`
- [GraphQL types](https://github.com/graphql-go/graphql/blob/master/types.go): `types.go`
- [Document validation](https://github.com/graphql-go/graphql/blob/master/validator.go): `validator.go`
- [Validation rules](https://github.com/graphql-go/graphql/blob/master/rules.go): `rules.go`
- [Operation executor](https://github.com/graphql-go/graphql/blob/master/executor.go): `executor.go`
- [Execution planning](https://github.com/graphql-go/graphql/blob/master/plan.go): `plan.go`
- [Input and output values](https://github.com/graphql-go/graphql/blob/master/values.go): `values.go`
- [Subscriptions](https://github.com/graphql-go/graphql/blob/master/subscription.go): `subscription.go`
- [Introspection](https://github.com/graphql-go/graphql/blob/master/introspection.go): `introspection.go`

### Language Tooling

- [AST visitor](https://github.com/graphql-go/graphql/blob/master/language/visitor/visitor.go): `language/visitor/visitor.go`
- [AST type info](https://github.com/graphql-go/graphql/blob/master/language/typeInfo/type_info.go): `language/typeInfo/type_info.go`
- [AST printer](https://github.com/graphql-go/graphql/blob/master/language/printer/printer.go): `language/printer/printer.go`

### Other components

- **GraphQL client**

## Connections

- GraphQL client → Operation request: submits
- Operation request → Do entry point: provides input
- Do entry point → Parser: parses operation
- Parser → Source text: reads text
- Parser → Lexer: requests tokens
- Lexer → Source text: scans text
- Parser → GraphQL AST: builds AST
- Do entry point → Document validation: validates operation
- Document validation → Validation rules: applies rules
- Document validation → Schema: checks against
- Do entry point → Operation executor: executes operation
- Operation executor → Schema: resolves against
- Operation executor → Execution planning: plans execution
- Operation executor → Input and output values: coerces values
- Do entry point → Subscriptions: dispatches subscription
- Subscriptions → Schema: uses schema
- Schema → GraphQL types: contains type definitions
- Schema → Introspection: provides introspection
- Do entry point → GraphQL errors: reports errors
- Document validation → AST visitor: traverses AST
- Validation rules → AST visitor: defines visitors
- AST visitor → AST type info: maintains type context
- AST printer → AST visitor: prints AST nodes
- Do entry point → Execution result: returns result
- Execution result → GraphQL client: delivers data