# netflix/dgs-codegen architecture

> Architecture diagram of the GitHub repository netflix/dgs-codegen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netflix/dgs-codegen
- Repository: https://github.com/netflix/dgs-codegen

## Overview

##### Project type and purpose
- This is an open-source, multi-module Gradle plugin (“DGS Code Generation Plugin”) that reads GraphQL schema files and produces type-safe Java/Kotlin client APIs, constants, and example data fetchers during a build.

##### Top-level modules and their roles
- **graphql-dgs-codegen-core** (Kotlin/Java library)
- Core engine: parses GraphQL schemas → builds IR (intermediate representation) → invokes generators
- Contains subpackages for Java, Kotlin, and Kotlin2 code generators
- Exposes a CLI entry point (CodeGenCli) for ad-hoc codegen outside Gradle
- **graphql-dgs-codegen-shared-core** (Kotlin library)
- Shared client-side runtime types (projections, serializers)
- Utilities for GraphQL requests, input/value sanitization, reserved-keyword filtering
- **graphql-dgs-codegen-gradle** (Gradle plugin)
- Defines a PluginExtension and a GenerateJavaTask (and analogous Kotlin tasks)
- Reads user configuration, locates schema files, calls into codegen-core’s API
- Hooks into the standard Gradle lifecycle (compileJava, compileKotlin)

##### Main components
- **Input**: GraphQL schema file(s) (user project)
- **Gradle Plugin**:
- PluginExtension (configuration DSL)
- Generate*Task(s)
- **CodeGen Core**:
- Schema parser → IR builder
- Language generators (JavaGenerator, KotlinGenerator, Kotlin2Generator)
- Uses JavaPoet/KotlinPoet under the covers
- **Shared Core**:
- Runtime client code (projections, serializers)
- Code used by generated code at runtime
- **Output**: Generated source files (DgsClient, DgsConstants, data types, interfaces)

##### Relationships and data flow
- The **Gradle Plugin** reads configuration → discovers schema files → passes schema paths + config to **CodeGen Core** APIs
- **CodeGen Core** parses schemas → builds IR → invokes each language generator → emits source code
- Generated code references types/utilities from **Shared Core**
- Optionally, the **CLI** can be invoked directly (outside Gradle) to drive **CodeGen Core** and get the same outputs

##### Important architectural patterns/principles
- **Modular layering**: plugin orchestration layer → core engine → shared client runtime
- **Separation of concerns**: parsing/IR, code generation, runtime utilities, build integration
- **Extensibility**: multiple language backends (Java/Kotlin/Kotlin2) implemented via shared generator interfaces
- **Plugin integration**: standard Gradle “Plugin → Task → Action” pattern

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Artifacts
    Input["GraphQL Schema Files"]:::artifact
    Generated["Generated Source Files"]:::artifact

    %% Gradle Plugin Layer
    subgraph "Gradle Plugin"
        Extension["PluginExtension"]:::gradlePlugin
        Plugin["CodegenPlugin (Plugin)"]:::gradlePlugin
        Task["GenerateJavaTask"]:::gradlePlugin
    end

    %% CodeGen Core & CLI
    subgraph "CodeGen Core & CLI"
        Core["CodeGen (Core Engine)"]:::coreEngine
        CLI["CodeGen CLI"]:::coreEngine
        IR["IR Builder (RequiredTypeCollector)"]:::coreEngine
        JavaGen["Java Generators"]:::coreEngine
        KotlinGen["Kotlin Generators"]:::coreEngine
        Kotlin2Gen["Kotlin2 Generators"]:::coreEngine
    end

    %% Shared Core Runtime
    subgraph "Shared Core"
        Runtime["Runtime Client Types"]:::sharedRuntime
        Sanitizers["Sanitizers & Serializers"]:::sharedRuntime
    end

    %% Relationships
    Input -->|reads schema files| Task
    Extension -->|configures| Task
    Plugin -->|registers task| Task
    Task -->|"invoke generate()"| Core
    Core -->|builds IR| IR
    Core -->|"invoke generators"| JavaGen
    Core -->|"invoke generators"| KotlinGen
    Core -->|"invoke generators"| Kotlin2Gen
    JavaGen -->|"emit .java/.kt"| Generated
    KotlinGen -->|"emit .kt"| Generated
    Kotlin2Gen -->|"emit .kt"| Generated
    Generated -->|"runtime dependency"| Runtime
    Generated -->|"runtime dependency"| Sanitizers
    Input -->|ad-hoc use| CLI
    CLI -->|"invoke generate()"| Core

    %% Click Events
    click Input "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-gradle/src/test/resources/test-project/src/main/resources/schema/schema.graphqls"
    click Extension "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-gradle/src/main/java/com/netflix/graphql/dgs/codegen/gradle/CodegenPluginExtension.java"
    click Plugin "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-gradle/src/main/kotlin/com/netflix/graphql/dgs/codegen/gradle/CodegenPlugin.kt"
    click Task "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-gradle/src/main/kotlin/com/netflix/graphql/dgs/codegen/gradle/GenerateJavaTask.kt"
    click Core "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/CodeGen.kt"
    click CLI "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/CodeGenCli.kt"
    click IR "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/RequiredTypeCollector.kt"
    click JavaGen "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/generators/java/ClientApiGenerator.kt"
    click KotlinGen "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/generators/kotlin/KotlinDataTypeGenerator.kt"
    click Kotlin2Gen "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-core/src/main/kotlin/com/netflix/graphql/dgs/codegen/generators/kotlin2/GenerateKotlin2ClientTypes.kt"
    click Runtime "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-shared-core/src/main/kotlin/com/netflix/graphql/dgs/client/codegen/BaseProjectionNode.kt"
    click Sanitizers "https://github.com/netflix/dgs-codegen/blob/master/graphql-dgs-codegen-shared-core/src/main/kotlin/com/netflix/graphql/dgs/client/codegen/InputValueSerializer.kt"

    %% Styles
    classDef gradlePlugin fill:#D6EAF8,stroke:#1F618D;
    classDef coreEngine fill:#D1F2EB,stroke:#148F77;
    classDef sharedRuntime fill:#FCF3CF,stroke:#B7950B;
    classDef artifact fill:#F2F4F4,stroke:#85929E;
```
