# eh3rrera/graphql-java-spring-boot-example architecture

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

- Interactive diagram: https://gitdiagram.com/eh3rrera/graphql-java-spring-boot-example
- Repository: https://github.com/eh3rrera/graphql-java-spring-boot-example

## Overview

##### Project type and purpose
- This is a backend‐only Spring Boot application that exposes a GraphQL API.
- Purpose: serve a GraphQL endpoint for querying and mutating Book and Author data, backed by an in-memory H2 database.

##### File structure
- Top level: pom.xml, Maven wrapper files, application entry point (DemoGraphQlApplication.java).
- src/main/java/com/example/DemoGraphQL:
- model/ – domain entities (Book, Author)
- repository/ – Spring Data JPA interfaces (BookRepository, AuthorRepository)
- resolver/ – GraphQL resolvers (Query, Mutation, BookResolver)
- exception/ – custom exceptions and error adapter for GraphQL
- MyProperties.java – custom configuration properties
- src/main/resources:
- application.yml – Spring Boot config (H2 console, datasource)
- graphql/*.graphqls – schema definitions for Query/Mutation types
- src/test: unit tests for application startup and Query resolver

##### Key points from README
- Uses Java 11/17, Spring Boot, graphql-java and graphql-spring-boot-starter.
- Runs on embedded Tomcat at localhost:8080
- Exposes GraphiQL, Altair, Playground, Voyager UIs.
- H2 in-memory DB accessible via Spring’s H2 console.

##### Main components and interactions (
a. Client layer:
- Browser (GraphiQL/Altair/Playground/Voyager UIs)
- Third-party GraphQL clients or other services consuming the API
b. Web/API layer:
- Spring Boot embedded web server (Tomcat)
- HTTP endpoint “/graphql” handling POST GraphQL requests
c. GraphQL engine:
- graphql-java Tools (schema parser, runtime wiring)
- Schema files loaded from classpath (author.graphqls, book.graphqls)
d. Resolver layer:
- Query resolver (fetch list of books, single book by ID)
- Mutation resolver (newBook)
- Field resolver (BookResolver to fetch nested Author for a Book)
- GraphQLErrorAdapter (to map exceptions to GraphQL errors)
e. Persistence layer:
- Spring Data JPA repositories
- JPA Entities (Book, Author)
f. Database:
- H2 in-memory database (jdbc:h2:mem:testdb)
g. Configuration:
- application.yml for datasource and GraphQL servlet settings
- MyProperties for any custom config

##### Relationships and data flow
1. Client (via browser UI or external tool) sends HTTP POST to /graphql
2. Spring Boot dispatches to GraphQL servlet
3. graphql-java parses query against schema
4. Query/Mutation resolver methods invoked
5. Resolvers call Spring Data JPA repositories
6. Repositories interact with H2 database
7. Data returned up the chain, serialized to JSON GraphQL response
8. Any exceptions thrown by resolvers are adapted by GraphQLErrorAdapter

##### Architectural patterns / design principles
- Separation of concerns:
- Controllers (GraphQL servlet) vs. business logic (resolver) vs. persistence (repository)
- Dependency injection: Spring Boot wiring of resolvers and repositories
- Schema-first GraphQL: GraphQL SDL files define contract
- Exception handling adapter to unify error responses

##### Technologies / frameworks / libraries
- Java 11/17
- Spring Boot (web, data-jpa, configuration properties)
- graphql-java, graphql-spring-boot-starter, graphql-java-tools
- H2 Database
- Maven build (pom.xml)

##### Final checklist
- [ ] All components labeled (Client UIs, HTTP Endpoint, GraphQL Engine, Resolvers, Repositories, DB)
- [ ] Callouts for key configuration (application.yml, MyProperties) and SDL files
- [ ] Notes on exception handling (GraphQLErrorAdapter)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        style ClientLayer fill:#E0F7FA,stroke:#000
        GR["GraphiQL UI"]:::clients
        AT["Altair UI"]:::clients
        PL["Playground UI"]:::clients
        VO["Voyager UI"]:::clients
        EXT["External GraphQL Client"]:::clients
    end

    subgraph "API Layer"
        style APILayer fill:#BBDEFB,stroke:#000
        APP["DemoGraphQlApplication"]:::api
        EP["/graphql Endpoint (POST)"]:::api
    end

    subgraph "Configuration"
        style ConfigLayer fill:#F3E5F5,stroke:#000
        YML["application.yml"]:::config
        PROP["MyProperties"]:::config
    end

    subgraph "GraphQL Engine"
        style EngineLayer fill:#E1BEE7,stroke:#000
        SE["Schema Files"]:::engine
        PARSE["graphql-java Parser & Runtime"]:::engine
    end

    subgraph "Resolver Layer"
        style ResolverLayer fill:#C8E6C9,stroke:#000
        QRY["Query Resolver"]:::resolver
        MUT["Mutation Resolver"]:::resolver
        BR["BookResolver"]:::resolver
        ERR["GraphQLErrorAdapter"]:::resolver
    end

    subgraph "Persistence Layer"
        style PersistenceLayer fill:#FFE0B2,stroke:#000
        AREP["AuthorRepository"]:::repo
        BREP["BookRepository"]:::repo
        ENT["Entities (Book, Author)"]:::repo
    end

    H2["H2 In-Memory Database"]:::db

    %% Flow
    GR -->|invoke| EP
    AT -->|invoke| EP
    PL -->|invoke| EP
    VO -->|invoke| EP
    EXT -->|invoke| EP

    EP -->|dispatch| PARSE
    SE -->|load SDL| PARSE

    PARSE -->|execute| QRY
    PARSE -->|execute| MUT
    QRY -->|field resolver| BR

    QRY -->|uses| AREP
    MUT -->|uses| BREP
    BR -->|uses| AREP

    AREP -->|JPA query| H2
    BREP -->|JPA query| H2

    H2 -->|return rows| AREP
    H2 -->|return rows| BREP

    AREP -->|return entities| QRY
    BREP -->|return entities| MUT

    ERR -.->|adapts| QRY
    ERR -.->|adapts| MUT
    ERR -.->|adapts| BR

    APP -->|configures| EP
    YML -->|configures| APP
    PROP -->|injected into| APP
    YML -->|SDL location| SE

    %% Click Events
    click APP "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/DemoGraphQlApplication.java"
    click PROP "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/MyProperties.java"
    click YML "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/resources/application.yml"
    click SE "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/resources/graphql/author.graphqls"
    click SE "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/resources/graphql/book.graphqls"
    click ENT "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/model/Author.java"
    click ENT "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/model/Book.java"
    click AREP "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/repository/AuthorRepository.java"
    click BREP "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/repository/BookRepository.java"
    click QRY "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/resolver/Query.java"
    click MUT "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/resolver/Mutation.java"
    click BR "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/resolver/BookResolver.java"
    click ERR "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/exception/GraphQLErrorAdapter.java"
    click ERR "https://github.com/eh3rrera/graphql-java-spring-boot-example/blob/master/src/main/java/com/example/DemoGraphQL/exception/BookNotFoundException.java"

    %% Styles
    classDef clients fill:#E0F7FA,stroke:#000,shape:circle
    classDef api fill:#BBDEFB,stroke:#000,shape:rect
    classDef config fill:#F3E5F5,stroke:#000,shape:rect
    classDef engine fill:#E1BEE7,stroke:#000,shape:rect
    classDef resolver fill:#C8E6C9,stroke:#000,shape:rect
    classDef repo fill:#FFE0B2,stroke:#000,shape:rect
    classDef db fill:#FFF59D,stroke:#000,shape:cylinder
```
