# wundergraph/graphql-go-tools architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source GraphQL Router / API Gateway framework written in Go.
- It’s a modular library (not a monolithic application) that you use to parse, validate, normalize, plan, and execute GraphQL operations—supporting Federation, Subscriptions (WS & SSE), custom DataSources, and more.
- It ships two major engine versions (v1 in maintenance; v2 actively developed), an execution helpers module, examples (e.g. federation gateway), test apps, and CI/CD pipelines.

##### File-structure analysis
– Top-level modules:
- /v2: the core v2 GraphQL engine (lexer, parser, ast, normalization, validation, planning, resolve).
- /execution: helpers to wire engine into request handlers.
- /pkg: shared packages (ast, parser, visitor, codegen, federation, subscription, http handler, etc.) used by both v1 and v2.
- /testapps: small demo apps (chat, kafka_pubsub) showing integration.
- CI: .github/workflows, Makefile, Go workspace (go.work).
– Architectural patterns:
- Layered pipeline: lexical analysis → AST construction → AST transforms (merge, normalization) → validation → planning → execution.
- Strategy pattern for DataSources (static, HTTP JSON, GraphQL, pub/sub, WASM, NATS, Kafka).
- Modular federation support (SDL merge, entity stitching, gateway poller).
- HTTP server abstraction with middleware, WebSocket & SSE support.
- Separate “v2” module to allow major rewrites side by side with v1.

##### Insights from README
– Distinct packages expose clear responsibilities (ast, astparser, astprinter, astvalidation, astnormalization, engine/plan, engine/resolve, subscription, http, playground).
– Execution module builds on the engine to simplify request handling.
– Examples show a federation gateway pulling configurations, polling sources, serving over HTTP/WS.
– Emphasis on high-throughput, low-GC, pluggable DataSources, OpenTelemetry, Prometheus.

a. Main components:
1. Client Layer: HTTP/GraphQL clients (REST clients, playground UI, websockets).
2. HTTP Server & Transport:
– HTTP handler (/pkg/http)
– WebSocket / SSE handler (/pkg/subscription and /pkg/http/ws)
– Middleware (authentication, complexity, tracing)
3. GraphQL Request Pipeline:
– Lexer (lexer/)
– Parser (astparser/)
– AST (ast/)
– AST Transform & Merge (asttransform/, federation/sdlmerge/)
– AST Normalization (astnormalization/)
– AST Validation (astvalidation/)
4. Planner & Execution Engine:
– Plan builder (engine/plan/)
– Resolver & Executor (engine/resolve/)
– Execution helpers (execution/)
5. DataSources (engine/datasource, execution/datasource):
– REST, HTTP JSON, GraphQL upstream, static, NATS/Kafka, MQTT, WASM, pipeline
6. Federation Gateway (examples/federation):
– Metadata poller, schema merge, entity resolvers
7. External Systems:
– Upstream APIs, databases, message buses, S3 (config store)
8. Tooling & Examples:
– Example apps (testapps/)
– Playground UI (playground/)
9. Packaging & CI/CD:
– go.work, Makefile, GitHub Actions

b. Relationships & interactions:
- Client → HTTP Server → GraphQL Pipeline → Planner → Executor → DataSource → External systems → back to executor → response writer → Client.
- Middleware intercepts HTTP requests/responses for auth, tracing, metrics.
- Execution module configures engine with DataSource factories & field mappings.

c. Architectural patterns & principles:
- Pipeline (chain of responsibility) for AST transformation.
- Strategy pattern for pluggable DataSource implementations.
- Modular separation (packages for AST, planning, execution).
- Versioning via Go workspace (v1 vs v2 modules).
- Example-driven integration (federation example, testapps).
- CI/CD gating and release automation (.github/workflows).

d. Key technologies & libraries:
- Go modules & workspace (go.work).
- gqlgen used in examples for GraphQL server scaffolding.
- WebSocket & SSE protocols for subscriptions.
- xxhash for cache key generation.
- Prometheus & OpenTelemetry hooks (in Cosmo Router).
- WASM execution via wasm_datasource.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["GraphQL/HTTP Clients"]:::client
    end

    subgraph "HTTP Server & Transport"
        HTTP_Handler["HTTP Handler"]:::transport
        WS_Handler["WebSocket Handler"]:::transport
        Sub_Handler["SSE/Subscription Handler"]:::transport
    end

    subgraph "Parsing & AST"
        Lexer["Lexer"]:::core
        Parser["Parser"]:::core
        AST_Model["AST Model"]:::core
    end

    subgraph "Transformation & Validation"
        AST_Transform["AST Transform & Merge"]:::core
        AST_Normalization["AST Normalization"]:::core
        AST_Validation["AST Validation"]:::core
    end

    subgraph "Planning"
        Plan_Builder["Plan Builder"]:::core
    end

    subgraph "Execution"
        Resolver_Executor["Resolver & Executor"]:::core
        Execution_Helpers["Execution Helpers"]:::extension
    end

    subgraph "DataSources"
        Core_Datasource["Core DataSource Interfaces"]:::extension
        Exec_Datasource["Execution-level DataSources"]:::extension
    end

    subgraph "Federation Support"
        SDL_Merge["SDL Merge"]:::extension
        Fed_Schema["Federation Schema Utils"]:::extension
    end

    subgraph "Examples & Test Apps"
        Fed_Gateway["Federation Gateway Example"]:::example
        Poller["Metadata Poller"]:::example
        Fed_HTTP["Example HTTP Handler"]:::example
        Chat["Chat Test App"]:::example
        Kafka["Kafka PubSub App"]:::example
    end

    subgraph "External Systems"
        External_API["Upstream APIs"]:::external
        MessageBus["Message Buses"]:::external
        S3["Config Store (S3)"]:::external
    end

    subgraph "CI/CD & Tooling"
        GH_Action["GitHub Actions"]:::ci
        Makefile["Makefile"]:::ci
        Go_Work["go.work"]:::ci
    end

    Client -->|"requests"| HTTP_Handler
    HTTP_Handler -->|"passes to"| Lexer
    WS_Handler -->|"passes to"| Lexer
    Sub_Handler -->|"passes to"| Lexer

    Lexer -->|"generates AST"| Parser
    Parser --> AST_Model
    AST_Model --> AST_Transform
    AST_Transform --> AST_Normalization
    AST_Normalization --> AST_Validation
    AST_Validation --> Plan_Builder
    Plan_Builder --> Resolver_Executor
    Resolver_Executor --> Core_Datasource
    Resolver_Executor --> Exec_Datasource
    Core_Datasource --> External_API
    Exec_Datasource --> MessageBus
    Exec_Datasource --> S3
    Resolver_Executor --> Execution_Helpers
    Execution_Helpers --> Resolver_Executor

    Fed_Gateway --> SDL_Merge
    SDL_Merge --> AST_Transform
    Fed_Gateway --> Fed_Schema
    Fed_Gateway --> Poller
    Poller --> External_API
    Fed_Gateway --> Fed_HTTP
    Fed_HTTP --> HTTP_Handler

    Chat --> HTTP_Handler
    Kafka --> Sub_Handler

    GH_Action --> Makefile
    Makefile --> Go_Work

    classDef client fill:#EFEFFF,stroke:#0000FF,color:#000040;
    classDef transport fill:#E0FFF0,stroke:#008000,color:#004000;
    classDef core fill:#E0E0FF,stroke:#000080,color:#000040;
    classDef extension fill:#FFF8DC,stroke:#FFA500,color:#804000;
    classDef example fill:#FFF0F0,stroke:#FF0000,color:#800000;
    classDef external fill:#F0F0F0,stroke:#808080,color:#404040;
    classDef ci fill:#F8F8FF,stroke:#00008B,color:#000080;

    click HTTP_Handler "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/http/handler.go"
    click HTTP "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/http/http.go"
    click WS_Handler "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/http/ws.go"
    click Sub_Handler "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/subscription/handler.go"
    click Lexer "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/lexer/lexer.go"
    click Parser "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/astparser/parser.go"
    click AST_Model "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/ast/"
    click AST_Transform "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/asttransform/"
    click AST_Normalization "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/astnormalization/"
    click AST_Validation "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/astvalidation/"
    click Plan_Builder "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/engine/plan/plan.go"
    click Resolver_Executor "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/engine/resolve/resolve.go"
    click Exec_Engine "https://github.com/wundergraph/graphql-go-tools/blob/master/execution/engine/execution_engine.go"
    click GraphQL_HTTP "https://github.com/wundergraph/graphql-go-tools/blob/master/execution/graphql/request.go"
    click Sub_Engine "https://github.com/wundergraph/graphql-go-tools/blob/master/execution/subscription/engine.go"
    click Core_Datasource "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/engine/datasource/"
    click Exec_Datasource "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/execution/datasource/"
    click SDL_Merge "https://github.com/wundergraph/graphql-go-tools/tree/master/pkg/federation/sdlmerge/"
    click Fed_Schema "https://github.com/wundergraph/graphql-go-tools/blob/master/pkg/federation/schema.go"
    click Fed_Gateway "https://github.com/wundergraph/graphql-go-tools/blob/master/examples/federation/gateway/gateway.go"
    click Poller "https://github.com/wundergraph/graphql-go-tools/blob/master/examples/federation/gateway/datasource_poller.go"
    click Fed_HTTP "https://github.com/wundergraph/graphql-go-tools/blob/master/examples/federation/gateway/http/handler.go"
    click Chat "https://github.com/wundergraph/graphql-go-tools/tree/master/testapps/chat/"
    click Kafka "https://github.com/wundergraph/graphql-go-tools/tree/master/testapps/kafka_pubsub/"
    click GH_Action "https://github.com/wundergraph/graphql-go-tools/tree/master/.github/workflows/"
    click Makefile "https://github.com/wundergraph/graphql-go-tools/tree/master/Makefile"
    click Go_Work "https://github.com/wundergraph/graphql-go-tools/blob/master/go.work"
```
