# attic-labs/graphql architecture

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

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

## Overview

##### Project type and purpose
- This is a Go library implementing the core GraphQL specification (lexer, parser, AST, schema, validation, execution, printer) for use in Go applications.
- It is distributed as an open-source tool (a Go package) rather than a standalone server or full-stack app.

##### File structure
- Top-level files:
- graphql.go, executor.go, validator.go, schema.go, directives.go, scalars.go, introspection.go, definition.go – the core API entry points and orchestration.
- gqlerrors/ – error models and formatting.
- language/ – subpackages for the language pipeline:
- lexer/ – tokenizes GraphQL source
- parser/ – builds AST from tokens
- ast/ – AST node definitions
- printer/ – serializes AST back to GraphQL syntax
- typeInfo/ – collects type metadata
- visitor/ – generic AST traversal
- kinds/, location/, source/ – supporting utilities
- testutil/ – test harnesses for validation, introspection, etc.
- examples/ – sample standalone programs demonstrating usage in different contexts (HTTP handler, context, todo, star-wars).
- tests scattered alongside code (e.g. *_test.go).

##### README for additional insights
- Confirms this is a work-in-progress port of graphql-js.
- Lists supported features: lexer, parser, schema parser, printer, executor, validator, visitor.
- Mentions recommended middleware (graphql-go-handler) for HTTP integration.

##### Elements
- Green for core pipeline modules
- Blue for supporting utilities (visitor, typeInfo)
- Yellow for error handling
- Grey for examples/tests
- Annotation of key public functions (graphql.Do, graphql.NewSchema).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    subgraph "Consumer Layer"
        Client["Client / HTTP Handler"]:::consumer
        EntryAPI["Entry API\n(graphql.Do, Params, NewSchema)"]:::core
    end
    Client -->|"Invoke graphql.Do"| EntryAPI
    click EntryAPI "https://github.com/attic-labs/graphql/blob/master/graphql.go"

    %% Source Processing
    subgraph "Source Processing"
        Source["GraphQL Source\nstring"]:::data
        Lexer["Lexer"]:::core
        Tokens["Tokens"]:::data
        Parser["Parser\n(includes Schema Parser)"]:::core
        DocumentAST["Document AST"]:::core
    end
    Source --> Lexer
    click Lexer "https://github.com/attic-labs/graphql/blob/master/language/lexer/lexer.go"
    Lexer --> Tokens
    Tokens --> Parser
    click Parser "https://github.com/attic-labs/graphql/blob/master/language/parser/parser.go"
    Parser --> DocumentAST
    click DocumentAST "https://github.com/attic-labs/graphql/tree/master/language/ast/"

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        TypeInfo["TypeInfo Collector"]:::util
        Visitor["AST Visitor"]:::util
        Kinds["Kinds"]:::util
        Location["Location"]:::util
        SourceUtil["Source"]:::util
        Printer["Printer"]:::core
    end
    click TypeInfo "https://github.com/attic-labs/graphql/blob/master/language/typeInfo/type_info.go"
    click Visitor "https://github.com/attic-labs/graphql/blob/master/language/visitor/visitor.go"
    click Kinds "https://github.com/attic-labs/graphql/blob/master/language/kinds/kinds.go"
    click Location "https://github.com/attic-labs/graphql/blob/master/language/location/location.go"
    click SourceUtil "https://github.com/attic-labs/graphql/blob/master/language/source/source.go"
    click Printer "https://github.com/attic-labs/graphql/blob/master/language/printer/printer.go"
    DocumentAST --> Printer

    %% Schema Parsing
    subgraph "Schema Layer"
        EntryAPI -->|"Build Schema"| SchemaParser["Schema Parser"]:::core
        SchemaParser --> SchemaAST["Schema AST"]:::core
    end
    click SchemaParser "https://github.com/attic-labs/graphql/blob/master/schema.go"
    click SchemaParser "https://github.com/attic-labs/graphql/blob/master/definition.go"
    click SchemaParser "https://github.com/attic-labs/graphql/blob/master/introspection.go"
    click SchemaParser "https://github.com/attic-labs/graphql/blob/master/directives.go"
    click SchemaParser "https://github.com/attic-labs/graphql/blob/master/scalars.go"
    SchemaAST --> Validator

    %% Validation
    subgraph "Validation Layer"
        Validator["Validator\n(validator.go, rules.go)"]:::core
        ErrorHandler["Error Handling\n(gqlerrors)"]:::error
    end
    click Validator "https://github.com/attic-labs/graphql/blob/master/validator.go"
    click Validator "https://github.com/attic-labs/graphql/blob/master/rules.go"
    click ErrorHandler "https://github.com/attic-labs/graphql/blob/master/gqlerrors/error.go"
    click ErrorHandler "https://github.com/attic-labs/graphql/blob/master/gqlerrors/formatted.go"
    click ErrorHandler "https://github.com/attic-labs/graphql/blob/master/gqlerrors/located.go"
    click ErrorHandler "https://github.com/attic-labs/graphql/blob/master/gqlerrors/syntax.go"
    DocumentAST --> Validator
    Validator -->|"Errors"| ErrorHandler
    Validator -->|"Valid"| Executor

    %% Execution
    subgraph "Execution Layer"
        Executor["Executor"]:::core
        ExecutionResult["Result"]:::data
    end
    click Executor "https://github.com/attic-labs/graphql/blob/master/executor.go"
    EntryAPI --> Executor
    Executor --> ExecutionResult
    ErrorHandler -->|Formatted Errors| ExecutionResult
    ExecutionResult --> Client

    %% Examples & Tests
    subgraph "Examples & Tests"
        Examples["Examples (sample programs)"]:::grey
        TestUtils["Test Utilities & Harness"]:::grey
    end
    click Examples "https://github.com/attic-labs/graphql/tree/master/examples/"
    click TestUtils "https://github.com/attic-labs/graphql/blob/master/testutil/testutil.go"
    click TestUtils "https://github.com/attic-labs/graphql/blob/master/testutil/rules_test_harness.go"
    click TestUtils "https://github.com/attic-labs/graphql/blob/master/testutil/introspection_query.go"

    %% Styles
    classDef core fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef util fill:#c2dfff,stroke:#333,stroke-width:1px
    classDef error fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef grey fill:#eaeaea,stroke:#333,stroke-width:1px
    classDef data fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef consumer fill:#e6ffe6,stroke:#333,stroke-width:1px
```
