# graphql-hive/gateway architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source GraphQL API Gateway (“Hive Gateway”) monorepo.
- Key deliverables: a CLI/binary entrypoint, a configurable GraphQL server runtime, pluginable execution pipeline, and support for multiple deployment targets (Node, Bun, Docker, Cloud Functions, Workers).

##### Top-Level Architectural Components
- CLI / Binary Launcher (packages/gateway/src/bin.ts & cli.ts)
- Gateway Server & Configuration Loader (packages/gateway/src/index.ts, config.ts)
- Runtime Core (packages/runtime & packages/fusion-runtime)
- Plugin System (packages/runtime/src/plugins + packages/plugins/*)
- Request Execution Pipeline
– Parsing & Validation (built-in GraphQL library)
– Delegation/Planning (packages/delegate, batch-delegate, stitch)
– Batching & Execution (packages/batch-execute, executors/http, executors/graphql-ws)
- Transport & Executors (HTTP, WebSocket, GraphQL-WS)
- Deployment Targets (Docker images, Node/Bun runtime, Cloudflare Workers)

##### Relationships & Data Flow
1. Client → HTTP / WebSocket / GraphQL-WS → CLI/Server entrypoint
2. Configuration Loader reads supergraph definition or proxy config.
3. Fusion-Runtime / UnifiedGraphManager builds in-memory schema graph.
4. Incoming GraphQL operation flows through the plugin stack (e.g. auth, metrics, caching).
5. Planner (delegate/stitch) splits the operation into subrequests.
7. Responses aggregated, merged, returned to client.

##### Architectural Patterns & Principles
- Modular monorepo: each package is a composable building block (batch delegate, delegate, stitch, wrap, federation, gateway, runtime).
- Plugin pipeline: hooks at critical phases (pre-parse, pre-execute, post-execute).
- Strategy / Factory patterns for executors & transports.
- Separation of concerns: configuration, planning, execution, transport are distinct modules.

##### Technologies & Frameworks
- Node.js & Bun support via rollup & custom binaries (packages/gateway).
- Yarn 2 workspaces, TypeScript.
- GraphQL core.
- Docker / Docker-Bake (docker-bake.hcl) for containerized deployment.
- CI/CD workflows (.github/workflows).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client"]:::external

    %% Entry Point Layer
    subgraph "Entrypoints" 
        direction TB
        CLI["CLI / Gateway Binary"]:::entry
        DockerImage["Docker Image"]:::entry
    end

    %% Server & Config
    subgraph "Server & Configuration" 
        direction TB
        ConfigLoader["Configuration Loader"]:::core
    end

    %% Runtime Core
    subgraph "Runtime Core" 
        direction TB
        UnifiedGraph["Unified Graph Manager"]:::core
        RuntimeCore["Runtime Core"]:::core
    end

    %% Plugin System
    subgraph "Plugin System" 
        direction TB
        Plugins["Plugin Stack"]:::extension
    end

    %% Planning and Execution
    subgraph "Planning & Execution" 
        direction TB
        Planner["Query Planner"]:::core
        subgraph "Executor Manager"
            direction TB
            Batching["Batching Engine"]:::extension
            HttpExec["HTTP Executor"]:::extension
            WsExec["WS Executor"]:::extension
        end
    end

    %% External Subgraphs
    subgraph "External Subgraphs" 
        direction TB
        Sub1["Subgraph 1"]:::external
        Sub2["Subgraph 2"]:::external
    end

    %% Deployment Targets
    subgraph "Deployment Targets" 
        direction TB
        NodeDocker["Node Docker"]:::entry
        BunDocker["Bun Docker"]:::entry
        Worker["Cloudflare Worker"]:::external
    end

    %% Data Flow
    Client -->|HTTP/WS/GraphQL-WS| CLI
    CLI -->|loads| ConfigLoader
    ConfigLoader -->|builds| UnifiedGraph
    UnifiedGraph -->|exposes| RuntimeCore
    RuntimeCore -->|hooks| Plugins
    RuntimeCore -->|plans| Planner
    Planner -->|executes| Batching
    Planner -->|executes| HttpExec
    Planner -->|executes| WsExec
    Batching -->|issues| Sub1
    HttpExec -->|issues| Sub1
    WsExec -->|issues| Sub1
    Batching -->|issues| Sub2
    HttpExec -->|issues| Sub2
    WsExec -->|issues| Sub2
    Sub1 -->|response| RuntimeCore
    Sub2 -->|response| RuntimeCore
    RuntimeCore -->|result| Client

    %% Click Events
    click CLI "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/bin.ts"
    click CLI "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/cli.ts"
    click CLI "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/rollup.config.binary.js"
    click ConfigLoader "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/index.ts"
    click ConfigLoader "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/config.ts"
    click ConfigLoader "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/getMaxConcurrency.ts"
    click ConfigLoader "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/src/servers/startServerForRuntime.ts"
    click RuntimeCore "https://github.com/graphql-hive/gateway/blob/main/packages/runtime/src/index.ts"
    click RuntimeCore "https://github.com/graphql-hive/gateway/blob/main/packages/runtime/src/createGatewayRuntime.ts"
    click UnifiedGraph "https://github.com/graphql-hive/gateway/blob/main/packages/fusion-runtime/src/index.ts"
    click UnifiedGraph "https://github.com/graphql-hive/gateway/blob/main/packages/fusion-runtime/src/unifiedGraphManager.ts"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/runtime/src/plugins/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/aws-sigv4/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/deduplicate-request/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/hmac-upstream-signature/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/jwt-auth/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/opentelemetry/"
    click Plugins "https://github.com/graphql-hive/gateway/tree/main/packages/plugins/prometheus/"
    click Planner "https://github.com/graphql-hive/gateway/tree/main/packages/delegate/src/"
    click Planner "https://github.com/graphql-hive/gateway/tree/main/packages/batch-delegate/src/"
    click Planner "https://github.com/graphql-hive/gateway/tree/main/packages/stitch/src/"
    click Batching "https://github.com/graphql-hive/gateway/tree/main/packages/batch-execute/src/"
    click HttpExec "https://github.com/graphql-hive/gateway/tree/main/packages/executors/http/src/"
    click WsExec "https://github.com/graphql-hive/gateway/tree/main/packages/executors/graphql-ws/src/"
    click NodeDocker "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/node.Dockerfile"
    click BunDocker "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/bun.Dockerfile"
    click NodeDocker "https://github.com/graphql-hive/gateway/blob/main/docker-bake.hcl"
    click NodeDocker "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/node_e2e.Dockerfile"
    click BunDocker "https://github.com/graphql-hive/gateway/blob/main/packages/gateway/bun_e2e.Dockerfile"

    %% Styles
    classDef entry fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef extension fill:#fc6,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
```
