How 99designs/gqlgen works
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.