# 99designs/gqlgen architecture

> Architecture diagram of the GitHub repository 99designs/gqlgen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/99designs/gqlgen
- Repository: https://github.com/99designs/gqlgen

## Overview

##### Main components
- CLI/Entry-Point: The project’s main.go, the command routines (for “init”, “generate”, etc.) and tools (like the “client” package) kick off the code generation workflow.
- Configuration & Codegen Engine: The “codegen” folder (with its templates, config parsers, resolvers, and field handling) is the heart of the generation engine that reads GraphQL schema files and user‐provided gqlgen.yml configuration.
- GraphQL Schema Parsing and Model Generation: The “graphql” package manages schema parsing, coercion, type checking, and generating type-safe Go models. It works closely with configuration options (defined in files such as gqlgen.yml).
- GraphQL Execution & Runtime: The “handler” and “graphql/handler” directories hold the request handling logic – transports like HTTP, Websocket and SSE – and plug in extensions (e.g., for complexity, introspection, federation) to support GraphQL query execution.
- Plugins and Extensions: Under the “plugin” directory, various plugins are implemented to support federation, custom resolver generation, server generation and model customization. These components extend the built-in code generation and runtime capabilities.
- Examples, Tests, and Integration: The extensive “_examples”, “integration”, and “testdata” directories illustrate use cases and test various functionalities – offering integration tests and sample implementations.
- Internal Utilities: The “internal” folders (like “code”, “imports”, “rewrite”) contain utility routines for deeper operations, dependency management, and code rewriting for the code generation process.

##### Relationships and Interactions
- The CLI and main.go act as the entry point. They invoke the code generation engine that starts by reading configuration (gqlgen.yml) and GraphQL schema definitions.
- The codegen engine (with its configuration packages and templates) processes the schema using the “graphql” package’s parsing routines, and then outputs Go models and resolver stubs.
- The generated code is integrated with the GraphQL execution engine (in handler/ and graphql/handler/) that provides runtime support along with middleware, extensions, and transport mechanisms.
- Plugins and additional packages (in plugin/) are used to add advanced functionalities (such as federation support) and to customize model and resolver generation.
- Integration tests and examples validate the flow – from schema definition to generation and execution – ensuring the end-to-end quality of the GraphQL server.

##### Architectural patterns/design principles
- Schema-first design: The system is designed around the GraphQL schema definition that drives code generation.
- Code Generation and Type Safety: The project emphasizes generating type-safe Go code from GraphQL schemas and configuration, avoiding generic map types.
- Modular and Extensible design: Use of plugins and clearly separated packages (codegen, handler, graphql) allow for customization and plug-in functionality.
- Separation of Concerns: The generation engine, runtime execution, and utility functions are housed in distinct modules, ensuring maintainability and clarity.

##### Technologies, frameworks, and libraries
- Language: Go
- GraphQL Server Paradigm: Using Schema Definition Language (SDL) to drive generation.
- CI/CD and Testing: Numerous GitHub workflows, integration tests, and examples show a strong focus on reliability.
- The project also supports different transport mechanisms (HTTP, Websocket, SSE) and extensions (federation, complexity analysis, introspection).

##### Elements
- Use clear, descriptive labels for each major component:
- CLI / Entry Point (main.go, tools.go, client)
- Configuration Manager (gqlgen.yml & config parsing in codegen/config)
- Code Generation Engine (codegen package – templates, resolver generation)
- Schema Parser & Model Generator (graphql package)
- Runtime & Request Handler (handler, graphql/handler/transport)
- Plugin Subsystems (plugin/federation, plugin/resolvergen, etc.)
- Example & Integration Tests (integration, _examples)
- From CLI → Config Manager → Code Generation Engine
- From Code Generation Engine → Generated Models & Resolvers
- From GraphQL Executor (Runtime) ← Resolver logic
- Core libraries (e.g., graphql, handler)
- Code generation components (codegen, configuration)
- Extensions or plugins (plugin)
- Examples, tests, and integrations (integration, _examples)

##### Final Recommendations
- Clearly separate the “build time” aspects (code generation, configuration processing) from the “runtime” aspects (request handling, resolver execution).
- Labels and annotations, such as “Schema-first Approach”, “Type-safe Codegen”, and “Extensible Plugin System” to help illustrate the key design principles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Time Subgraph
    subgraph "Build Time"
        A["CLI / Entry-Point (main.go)"]:::cli
        B["Configuration Manager (gqlgen.yml & config)"]:::generation
        C["Code Generation Engine"]:::generation
        D["Schema Parser & Model Generator"]:::parsing
        I["Internal Utilities"]:::utilities
        A --> B
        B --> C
        C --> D
        I --> C
    end

    %% Runtime Subgraph
    subgraph "Runtime"
        E1["Request Handler (HTTP, Websocket, SSE)"]:::runtime
        E2["GraphQL Handler (Transports & Extensions)"]:::runtime
    end
    
    %% Plugins and Extensions
    F["Plugins & Extensions"]:::plugin
    F --> C
    F --> E1
    F --> E2

    %% Flow from Build Time to Runtime
    D --> E1
    D --> E2

    %% Examples and Integration Tests
    G["Examples (_examples)"]:::examples
    H["Integration Tests"]:::examples
    G --> E1
    G --> E2
    H --> E1
    H --> E2

    %% Click Events
    click A "https://github.com/99designs/gqlgen/blob/master/main.go"
    click B "https://github.com/99designs/gqlgen/tree/master/codegen/config"
    click C "https://github.com/99designs/gqlgen/tree/master/codegen/"
    click D "https://github.com/99designs/gqlgen/tree/master/graphql/"
    click E1 "https://github.com/99designs/gqlgen/tree/master/handler/"
    click E2 "https://github.com/99designs/gqlgen/tree/master/graphql/handler/"
    click F "https://github.com/99designs/gqlgen/tree/master/plugin/"
    click G "https://github.com/99designs/gqlgen/tree/master/_examples/"
    click H "https://github.com/99designs/gqlgen/tree/master/integration/"
    click I "https://github.com/99designs/gqlgen/tree/master/internal/"

    %% Styles
    classDef cli fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef generation fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef parsing fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef runtime fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef plugin fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef examples fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef utilities fill:#d5f5e3,stroke:#333,stroke-width:2px;
```
