# spring-projects/spring-graphql architecture

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

- Interactive diagram: https://gitdiagram.com/spring-projects/spring-graphql
- Repository: https://github.com/spring-projects/spring-graphql

## Overview

##### Project Type and Purpose
- This is an open-source, multi-module Gradle project implementing “Spring for GraphQL” – a library that provides GraphQL support for Spring applications (both server-side and client-side).
- It also includes a testing module, a documentation site (Antora/Asciidoc), custom Gradle plugins (in buildSrc), and continuous-integration/deployment pipelines via GitHub Actions.

##### Top-Level Module Breakdown
- buildSrc: custom Gradle plugins (ConventionsPlugin, ArchitecturePlugin, etc.) that enforce code conventions, architecture checks, publishing conventions.
- spring-graphql (core library):
- Packages: execution, server, client, data, observation, support, etc.
- Exposes GraphQlRequest/Response APIs, server handlers (WebFlux/WebMVC, RSocket), client transports, data-repository abstractions.
- spring-graphql-test: testing utilities and GraphQlTester implementations for HTTP, WebSocket, RSocket, in-memory execution.
- spring-graphql-docs: Antora-based documentation website, code samples, Asciidoc sources, Maven publishing for docs.
- Platform & root: central Gradle configuration (publishing.gradle, settings.gradle), CI workflows, CODE_OF_CONDUCT, LICENSE, README.

- Core Library Module (spring-graphql):
- “Execution” subcomponent: GraphQlSource, RuntimeWiringConfigurer, DataFetcher registry.
- “Server” subcomponent: WebFlux/WebMVC HTTP handlers, WebSocket/RSocket handlers/interceptors.
- “Client” subcomponent: HTTP, WebSocket, RSocket transports, GraphQlClient builder classes.
- “Data” subcomponent: GraphQlRepository, Federation, Pagination, QueryByExample.
- “Observation” instrumentation: Micrometer context integration for request/response tracing.
- Testing Module (spring-graphql-test): GraphQlTester abstractions, transport simulators – depends on Core Library.
- Documentation Site (spring-graphql-docs): pulls code examples from Core and Test modules, builds via Antora, deploys to docs.spring.io.
- Build & Release Pipeline:
- buildSrc plugins → Gradle build → run tests → assemble JARs.
- GitHub Actions: CI (ci.yml), snapshot build, release workflows, docs deploy, Maven Central sync.
- External Dependencies/Services:
- GraphQL Java engine (third-party library dependency).
- Maven Central (artifact publishing).
- GitHub (source repo, Actions).
- Asciidoctor/Antora for docs.
- SDKMAN for environment setup (.sdkmanrc).

##### Relationships and Data Flows
- Core Library → GraphQL Java (runtime dependency).
- Core Library → Micrometer Context (observation).
- Testing Module → Core Library (compile/test-time dependency).
- Docs → Core/Test modules (source code inclusion for examples).
- buildSrc → all modules (plugin application).
- GitHub Actions → Gradle build (trigger) → deploy artifacts to Maven Central & docs site.

##### Architectural Patterns & Principles
- Multi-module Gradle project for separation of concerns (core, test, docs, build logic).
- Plugin-driven conventions for consistent builds and enforceable architecture rules.
- Layered decomposition within core: execution engine, transport handlers, data abstraction, client API.
- Open-closed extension points: GraphQlSourceBuilder, RuntimeWiringConfigurer, GraphQlClientInterceptor.
- CI/CD as code (GitHub Actions), with staged release, snapshot/published docs workflows.

##### Essential Elements to Capture
- Clear module boundaries and internal layering of the spring-graphql core.
- Build logic separation (buildSrc + platform).
- CI/CD connections (GitHub Actions workflows, release vs. snapshot vs. docs pipelines).
- External integrations (GraphQL Java, Maven Central, Antora).
- Test harness module and its relation to core producers and consumers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Developer Application
    DevApp["Developer Application"]:::external

    %% Build Logic & Custom Plugins
    subgraph "Build Logic & Custom Plugins"
        BSDir["buildSrc"]:::build
        ConventionsPlugin["ConventionsPlugin"]:::build
        ArchitecturePlugin["ArchitecturePlugin"]:::build
    end

    %% Platform & Root Configuration
    subgraph "Platform & Root"
        PublishingGradle["publishing.gradle"]:::platform
        PlatformBuildGradle["platform/build.gradle"]:::platform
        SettingsGradle["settings.gradle"]:::platform
    end

    %% Core Library Module
    subgraph "Core Library (spring-graphql)"
        CoreBuildGradle["build.gradle"]:::core
        CoreSrc["src/main/java/org/springframework/graphql"]:::core
        subgraph "Execution"
            Exec["execution"]:::core
        end
        subgraph "Server"
            Server["server"]:::core
        end
        subgraph "Client"
            Client["client"]:::core
        end
        subgraph "Data"
            Data["data"]:::core
        end
        subgraph "Observation"
            Obs["observation"]:::core
        end
        subgraph "Support"
            Sup["support"]:::core
        end
    end

    %% Testing Module
    subgraph "Testing Module (spring-graphql-test)"
        TestBuildGradle["build.gradle"]:::test
        TestSrc["src/main/java/org/springframework/graphql/test"]:::test
        TestTester["src/main/java/org/springframework/graphql/test/tester"]:::test
    end

    %% Documentation Site
    subgraph "Documentation Site (spring-graphql-docs)"
        DocsPlaybook["antora-playbook.yml"]:::docs
        DocsBuildGradle["build.gradle"]:::docs
        DocsPages["modules/ROOT/pages"]:::docs
        DocsAsciidoc["src/docs/asciidoc"]:::docs
    end

    %% CI/CD Workflows
    subgraph "CI/CD (GitHub Actions)"
        CI_CI["ci.yml"]:::ci
        CI_Snapshot["build-and-deploy-snapshot.yml"]:::ci
        CI_Release["release.yml"]:::ci
        CI_DeployDocs["deploy-docs.yml"]:::ci
    end

    %% External Services & Dependencies
    subgraph "External Dependencies"
        GraphQLJava["GraphQL Java"]:::external
        Micrometer["Micrometer Context"]:::external
        MavenCentral["Maven Central"]:::external
        Antora["Antora/Asciidoc"]:::external
        SDKMAN["SDKMAN"]:::external
    end

    %% Relationships
    DevApp -->|"compile-time"| Exec
    DevApp -->|"compile-time"| Server
    DevApp -->|"compile-time"| Client
    DevApp -->|"compile-time"| Data
    DevApp -->|"compile-time"| Obs

    Exec -->|"runtime"| GraphQLJava
    Server -->|"runtime"| GraphQLJava
    Client -->|"runtime"| GraphQLJava

    Obs -->|"uses"| Micrometer

    TestBuildGradle -->|"test-time dep on"| CoreBuildGradle
    TestSrc -->|"test-time dep on"| Exec
    TestTester -->|"test-time dep on"| Client

    DocsPlaybook -->|"includes examples from"| CoreSrc
    DocsPlaybook -->|"includes examples from"| TestSrc
    DocsBuildGradle -->|"deploys via"| Antora

    BSDir -->|"applies plugin to"| CoreBuildGradle
    BSDir -->|"applies plugin to"| TestBuildGradle
    BSDir -->|"applies plugin to"| DocsBuildGradle
    BSDir -->|"applies plugin to"| PlatformBuildGradle

    CI_CI -->|"triggers build"| BSDir
    CI_CI -->|"triggers build"| CoreBuildGradle
    CI_Snapshot -->|"publishes snapshot to"| MavenCentral
    CI_Release -->|"publishes release to"| MavenCentral
    CI_DeployDocs -->|"publishes docs to"| Antora

    %% Click Events for component mapping
    click BSDir "https://github.com/spring-projects/spring-graphql/tree/main/buildSrc/src/main/java/org/springframework/graphql/build"
    click ConventionsPlugin "https://github.com/spring-projects/spring-graphql/blob/main/buildSrc/src/main/java/org/springframework/graphql/build/ConventionsPlugin.java"
    click ArchitecturePlugin "https://github.com/spring-projects/spring-graphql/blob/main/buildSrc/src/main/java/org/springframework/graphql/build/architecture/ArchitecturePlugin.java"
    click CoreBuildGradle "https://github.com/spring-projects/spring-graphql/blob/main/spring-graphql/build.gradle"
    click CoreSrc "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql"
    click Exec "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/execution"
    click Server "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/server"
    click Client "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/client"
    click Data "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/data"
    click Obs "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/observation"
    click Sup "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql/src/main/java/org/springframework/graphql/support"
    click TestBuildGradle "https://github.com/spring-projects/spring-graphql/blob/main/spring-graphql-test/build.gradle"
    click TestSrc "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql-test/src/main/java/org/springframework/graphql/test"
    click TestTester "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql-test/src/main/java/org/springframework/graphql/test/tester"
    click DocsPlaybook "https://github.com/spring-projects/spring-graphql/blob/main/spring-graphql-docs/antora-playbook.yml"
    click DocsBuildGradle "https://github.com/spring-projects/spring-graphql/blob/main/spring-graphql-docs/build.gradle"
    click DocsPages "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql-docs/modules/ROOT/pages"
    click DocsAsciidoc "https://github.com/spring-projects/spring-graphql/tree/main/spring-graphql-docs/src/docs/asciidoc"
    click CI_CI "https://github.com/spring-projects/spring-graphql/blob/main/.github/workflows/ci.yml"
    click CI_Snapshot "https://github.com/spring-projects/spring-graphql/blob/main/.github/workflows/build-and-deploy-snapshot.yml"
    click CI_Release "https://github.com/spring-projects/spring-graphql/blob/main/.github/workflows/release.yml"
    click CI_DeployDocs "https://github.com/spring-projects/spring-graphql/blob/main/.github/workflows/deploy-docs.yml"
    click PublishingGradle "https://github.com/spring-projects/spring-graphql/blob/main/gradle/publishing.gradle"
    click PlatformBuildGradle "https://github.com/spring-projects/spring-graphql/blob/main/platform/build.gradle"
    click SettingsGradle "https://github.com/spring-projects/spring-graphql/blob/main/settings.gradle"

    %% Styles
    classDef core fill:#cce5ff,stroke:#0366d6,color:#0366d6;
    classDef test fill:#d4edda,stroke:#28a745,color:#155724;
    classDef docs fill:#fff3cd,stroke:#d39e00,color:#856404;
    classDef build fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef platform fill:#f0f0f0,stroke:#555555,color:#222222;
    classDef ci fill:#f5e6ff,stroke:#8a2be2,color:#5e2ca5;
    classDef external fill:#fde2e2,stroke:#e55353,color:#b02a37;
```
