# graphdsl/graphql-kotlin-dsl architecture

> Architecture diagram of the GitHub repository graphdsl/graphql-kotlin-dsl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/graphdsl/graphql-kotlin-dsl
- Repository: https://github.com/graphdsl/graphql-kotlin-dsl
- Video tour (about a minute): https://gitdiagram.com/graphdsl/graphql-kotlin-dsl/video

## Overview

GraphQL Kotlin DSL turns GraphQL schema files into type-safe Kotlin query and mutation builders that return GraphQL strings. The principal workflow is schema input → schema/type modeling → DSL generation → generated-source output wired into compilation; the CLI offers a separate generation entry point. The graph preserves query, mutation, input, object and interface generation as distinct capabilities. Sampled source confirms query-builder behavior, but not the full plugin/task or schema-parsing implementation, so uncertain internal wiring is omitted.

Main entry points: [`codegen/src/main/kotlin/io/github/graphdsl/codegen/DslFilesBuilder.kt`](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/DslFilesBuilder.kt) (DSL files builder), [`codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt`](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt) (Query generator), [`codegen/src/main/kotlin/io/github/graphdsl/codegen/mutationDslGen.kt`](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/mutationDslGen.kt) (Mutation generator), [`gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/task/GenerateDslTask.kt`](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/task/GenerateDslTask.kt) (Generation task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Generation entry points"]
  node_gradle_plugin["Gradle plugin<br/>[GraphDslPlugin.kt]"]
  node_generate_task["Generation task<br/>[GenerateDslTask.kt]"]
  node_cli["CLI generator"]
end

subgraph group_schema["Schema and types"]
  node_graphql_schema["Schema model<br/>[GraphDSLSchema.kt]"]
  node_schema_extensions["Schema extensions<br/>[GraphDSLSchema.kt]"]
  node_type_mapper["Type mapper<br/>[BaseTypeMapper.kt]"]
  node_value_mapper["Value mapping<br/>[ValueMapper.kt]"]
end

subgraph group_generation["DSL generation"]
  node_files_builder["DSL files builder<br/>[DslFilesBuilder.kt]"]
  node_query_generator["Query generator<br/>[queryDslGen.kt]"]
  node_query_field_generator["Query field generator"]
  node_mutation_generator["Mutation generator<br/>[mutationDslGen.kt]"]
  node_input_generator["Input generator<br/>[inputDslGen.kt]"]
  node_object_generator["Object generator<br/>[objectDslGen.kt]"]
  node_node_generator["Node interface generator"]
  node_template_utils["Template utilities<br/>[STUtils.kt]"]
end

subgraph group_output["Generated DSL"]
  node_generated_sources["Generated Kotlin DSL"]
  node_query_builder["Query string builder<br/>[queryDslGen.kt]"]
end

node_developer(("Kotlin developer"))
node_schema_files["GraphQL schema files"]
node_graphql_service(("GraphQL service"))

node_developer -->|"configures"| node_gradle_plugin
node_gradle_plugin -->|"registers"| node_generate_task
node_developer -.->|"runs"| node_cli
node_schema_files -->|"provides schema"| node_generate_task
node_schema_files -.->|"provides schema"| node_cli
node_generate_task -->|"invokes generation"| node_files_builder
node_cli -.->|"invokes generation"| node_files_builder
node_files_builder -->|"uses schema model"| node_graphql_schema
node_files_builder -->|"generates query"| node_query_generator
node_files_builder -->|"generates mutation"| node_mutation_generator
node_files_builder -->|"generates input"| node_input_generator
node_files_builder -->|"generates objects"| node_object_generator
node_files_builder -->|"generates interfaces"| node_node_generator
node_query_generator -->|"uses field builder"| node_query_field_generator
node_query_generator -->|"maps types"| node_type_mapper
node_query_field_generator -->|"maps types"| node_type_mapper
node_mutation_generator -->|"maps types"| node_type_mapper
node_query_generator -->|"builds template"| node_template_utils
node_mutation_generator -->|"builds template"| node_template_utils
node_files_builder -->|"writes sources"| node_generated_sources
node_generated_sources -->|"defines"| node_query_builder
node_developer -->|"calls generated DSL"| node_query_builder
node_query_builder -->|"sends query"| node_graphql_service
node_value_mapper -.->|"uses type definitions"| node_graphql_schema

click node_gradle_plugin "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/GraphDslPlugin.kt"
click node_generate_task "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/task/GenerateDslTask.kt"
click node_cli "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/cli/src/main/kotlin/io/github/graphdsl/cli/KotlinDslGenerator.kt"
click node_graphql_schema "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt"
click node_schema_extensions "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt"
click node_type_mapper "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/BaseTypeMapper.kt"
click node_value_mapper "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/mapper/src/main/kotlin/io/github/graphdsl/mapper/ValueMapper.kt"
click node_files_builder "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/DslFilesBuilder.kt"
click node_query_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt"
click node_query_field_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryFieldDslGen.kt"
click node_mutation_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/mutationDslGen.kt"
click node_input_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/inputDslGen.kt"
click node_object_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/objectDslGen.kt"
click node_node_generator "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/nodeInterfaceDslGen.kt"
click node_template_utils "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/shared/src/main/kotlin/io/github/graphdsl/codegen/st/STUtils.kt"
click node_query_builder "https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradle_plugin,node_generate_task,node_cli toneBlue
class node_graphql_schema,node_schema_extensions,node_type_mapper,node_value_mapper toneAmber
class node_files_builder,node_query_generator,node_query_field_generator,node_mutation_generator,node_input_generator,node_object_generator,node_node_generator,node_template_utils toneMint
class node_generated_sources,node_query_builder toneRose
class node_developer,node_schema_files,node_graphql_service toneIndigo
```

## Components

### Generation entry points

- [Gradle plugin](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/GraphDslPlugin.kt): `gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/GraphDslPlugin.kt`
- [Generation task](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/task/GenerateDslTask.kt): `gradle-plugins/graphdsl-plugin/src/main/kotlin/io/github/graphdsl/gradle/task/GenerateDslTask.kt`
- [CLI generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/cli/src/main/kotlin/io/github/graphdsl/cli/KotlinDslGenerator.kt): `cli/src/main/kotlin/io/github/graphdsl/cli/KotlinDslGenerator.kt`

### Schema and types

- [Schema model](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt): `schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt`
- [Schema extensions](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt): `schema/src/main/kotlin/io/github/graphdsl/schema/GraphDSLSchema.kt`
- [Type mapper](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/BaseTypeMapper.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/BaseTypeMapper.kt`
- [Value mapping](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/mapper/src/main/kotlin/io/github/graphdsl/mapper/ValueMapper.kt): `mapper/src/main/kotlin/io/github/graphdsl/mapper/ValueMapper.kt`

### DSL generation

- [DSL files builder](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/DslFilesBuilder.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/DslFilesBuilder.kt`
- [Query generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt`
- [Query field generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryFieldDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/queryFieldDslGen.kt`
- [Mutation generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/mutationDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/mutationDslGen.kt`
- [Input generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/inputDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/inputDslGen.kt`
- [Object generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/objectDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/objectDslGen.kt`
- [Node interface generator](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/nodeInterfaceDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/nodeInterfaceDslGen.kt`
- [Template utilities](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/shared/src/main/kotlin/io/github/graphdsl/codegen/st/STUtils.kt): `shared/src/main/kotlin/io/github/graphdsl/codegen/st/STUtils.kt`

### Generated DSL

- **Generated Kotlin DSL**
- [Query string builder](https://github.com/graphdsl/graphql-kotlin-dsl/blob/master/codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt): `codegen/src/main/kotlin/io/github/graphdsl/codegen/queryDslGen.kt`

### Other components

- **Kotlin developer**
- **GraphQL schema files**
- **GraphQL service**

## Connections

- Kotlin developer → Gradle plugin: configures
- Gradle plugin → Generation task: registers
- Kotlin developer → CLI generator: runs
- GraphQL schema files → Generation task: provides schema
- GraphQL schema files → CLI generator: provides schema
- Generation task → DSL files builder: invokes generation
- CLI generator → DSL files builder: invokes generation
- DSL files builder → Schema model: uses schema model
- DSL files builder → Query generator: generates query
- DSL files builder → Mutation generator: generates mutation
- DSL files builder → Input generator: generates input
- DSL files builder → Object generator: generates objects
- DSL files builder → Node interface generator: generates interfaces
- Query generator → Query field generator: uses field builder
- Query generator → Type mapper: maps types
- Query field generator → Type mapper: maps types
- Mutation generator → Type mapper: maps types
- Query generator → Template utilities: builds template
- Mutation generator → Template utilities: builds template
- DSL files builder → Generated Kotlin DSL: writes sources
- Generated Kotlin DSL → Query string builder: defines
- Kotlin developer → Query string builder: calls generated DSL
- Query string builder → GraphQL service: sends query
- Value mapping → Schema model: uses type definitions