How spring-projects/spring-graphql works
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.