# bourouishafsa261/graphql architecture

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

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

## Overview

1. **Overall shape**
   - This is a single Spring Boot **GraphQL monolith** for a books library.
   - The main runtime path is: GraphQL request → controller/resolver → Spring Data repositories → relational database.

2. **API contract boundary**
   - The GraphQL schema lives in `src/main/resources/graphql/schema.graphqls`.
   - That schema defines the public operations seen in the README: `books`, `booksByAuthor`, `search`, `addBook`, and `deleteAuthor`.
   - The API is shaped around GraphQL types and wrappers rather than REST resources.

3. **GraphQL execution layer**
   - `MyController` is the central application entry point for queries and mutations.
   - It likely contains the GraphQL handler methods that translate request arguments into repository lookups, validation, and response assembly.
   - There is no separate service package, so business logic appears to sit close to the controller/repository boundary.

4. **Domain model**
   - The core entities are `Book`, `Author`, and `Category`.
   - `Book` is the main aggregate exposed by the API and is associated with an author and a category.
   - `Category` appears to support hierarchy/recursion, which matters for the `recursive` book filtering behavior in the README.

5. **Persistence layer**
   - `AuthorRepo`, `BookRepo`, and `CategoryRepo` are Spring Data repositories.
   - These repositories are the main persistence abstraction and likely provide both CRUD and custom finder methods used by the GraphQL handlers.
   - `src/main/resources/data.sql` seeds the database with initial data for demo/testing.

6. **Query flows**
   - `books` supports pagination plus filters for publication year, language, and category.
   - The `recursive` category option suggests traversal of a category tree, not just a single category row.
   - `booksByAuthor` resolves books using either an author ID or author name.
   - `search` is a cross-entity lookup that returns books, authors, or categories from one endpoint.

7. **Mutation flows**
   - `addBook` is an admin-only write path that creates a book with references to an existing author and category.
   - The README shows duplicate-title validation per author, so mutation logic includes domain-level integrity checks, not just persistence.
   - `deleteAuthor` is also admin-only and deletes an author record, with effects depending on how book associations are handled in the underlying model.

8. **API response shaping**
   - `BookInput` is the mutation input object for creating books.
   - `BookPage`, `SearchPage`, and `PageInfo` are response wrappers used to return lists plus paging metadata.
   - This indicates the API does not expose raw repository results directly; it packages them into GraphQL-friendly view models.

9. **Security boundary**
   - `SecurityConfig` is the main authorization boundary.
   - Based on the README, read operations are public while admin mutations require authentication and role checks.
   - This is the key separation between anonymous API usage and privileged write access.

10. **Deployment and runtime packaging**
   - The project is Maven-based (`pom.xml`, Maven wrapper) and includes a `Dockerfile` for containerized deployment.
   - `ServletInitializer` suggests the app can also be deployed in a servlet container style, not just as a standalone jar.
   - The README shows it is deployed to Railway, but that is an external hosting target rather than a separate application subsystem.

11. **Tests**
   - `GraphQlDemoApplicationTests` is a minimal test entry point, likely a smoke test for Spring context startup.
   - There is no large test harness in the tree, so the repo is optimized more for demo/API delivery than extensive automated verification.

12. **How the pieces fit together**
   - Request enters GraphQL endpoint → schema selects operation → `MyController` handles it → repos query or mutate entities → response wrappers are built → security layer gates admin actions.
   - For diagramming, the important boundaries are: GraphQL contract, domain/repository layer, security, and database seeding/runtime deployment.

Main entry points: [`src/main/java/rs/master/courses/graphQlDemo/MyController.java`](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/MyController.java) (MyController), [`src/main/java/rs/master/courses/graphQlDemo/GraphQlDemoApplication.java`](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/GraphQlDemoApplication.java) (Application), [`src/main/java/rs/master/courses/graphQlDemo/Book.java`](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Book.java) (Book), [`src/main/java/rs/master/courses/graphQlDemo/BookRepo.java`](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookRepo.java) (BookRepo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Layer"]
  node_schema["GraphQL schema<br/>contract<br/>[schema.graphqls]"]
  node_controller["MyController<br/>graphql resolver<br/>[MyController.java]"]
  node_security["SecurityConfig<br/>auth config"]
end

subgraph group_domain["Domain & Persistence"]
  node_book["Book<br/>entity<br/>[Book.java]"]
  node_author["Author<br/>entity<br/>[Author.java]"]
  node_category["Category<br/>entity<br/>[Category.java]"]
  node_bookrepo["BookRepo<br/>[BookRepo.java]"]
  node_authorrepo["AuthorRepo<br/>[AuthorRepo.java]"]
  node_categoryrepo["CategoryRepo<br/>[CategoryRepo.java]"]
  node_bookinput["BookInput<br/>input model<br/>[BookInput.java]"]
  node_bookpage["BookPage<br/>page model<br/>[BookPage.java]"]
  node_searchpage["SearchPage<br/>result model<br/>[SearchPage.java]"]
  node_pageinfo["PageInfo<br/>pagination model<br/>[PageInfo.java]"]
end

subgraph group_runtime["Runtime & Packaging"]
  node_app["Application<br/>spring boot app"]
  node_servlet["ServletInitializer<br/>war bootstrap"]
  node_data["data.sql<br/>seed data<br/>[data.sql]"]
  node_docker["Dockerfile<br/>container build"]
  node_pom["pom.xml<br/>build config<br/>[pom.xml]"]
end

node_schema -->|"defines ops for"| node_controller
node_controller -->|"gated by"| node_security
node_controller -->|"queries"| node_bookrepo
node_controller -->|"queries"| node_authorrepo
node_controller -->|"queries"| node_categoryrepo
node_controller -->|"accepts"| node_bookinput
node_controller -->|"returns"| node_bookpage
node_controller -->|"returns"| node_searchpage
node_bookpage -->|"includes"| node_pageinfo
node_searchpage -->|"includes"| node_pageinfo
node_bookrepo -->|"manages"| node_book
node_authorrepo -->|"manages"| node_author
node_categoryrepo -->|"manages"| node_category
node_book -->|"links to"| node_author
node_book -->|"links to"| node_category
node_app -->|"built by"| node_pom
node_app -->|"loads"| node_data
node_servlet -->|"boots"| node_app
node_docker -->|"packages"| node_app

click node_schema "https://github.com/bourouishafsa261/graphql/blob/main/src/main/resources/graphql/schema.graphqls"
click node_controller "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/MyController.java"
click node_security "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/SecurityConfig.java"
click node_book "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Book.java"
click node_author "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Author.java"
click node_category "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Category.java"
click node_bookrepo "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookRepo.java"
click node_authorrepo "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/AuthorRepo.java"
click node_categoryrepo "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/CategoryRepo.java"
click node_bookinput "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookInput.java"
click node_bookpage "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookPage.java"
click node_searchpage "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/SearchPage.java"
click node_pageinfo "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/PageInfo.java"
click node_app "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/GraphQlDemoApplication.java"
click node_servlet "https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/ServletInitializer.java"
click node_data "https://github.com/bourouishafsa261/graphql/blob/main/src/main/resources/data.sql"
click node_docker "https://github.com/bourouishafsa261/graphql/tree/main/Dockerfile"
click node_pom "https://github.com/bourouishafsa261/graphql/blob/main/pom.xml"

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_schema,node_controller,node_security toneBlue
class node_book,node_author,node_category,node_bookrepo,node_authorrepo,node_categoryrepo,node_bookinput,node_bookpage,node_searchpage,node_pageinfo toneAmber
class node_app,node_servlet,node_data,node_docker,node_pom toneMint
```

## Components

### API Layer

GraphQL contract, request handling, and authorization

- [GraphQL schema](https://github.com/bourouishafsa261/graphql/blob/main/src/main/resources/graphql/schema.graphqls): contract · Public GraphQL operations and types · `src/main/resources/graphql/schema.graphqls`
- [MyController](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/MyController.java): graphql resolver · Handles queries and mutations · `src/main/java/rs/master/courses/graphQlDemo/MyController.java`
- [SecurityConfig](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/SecurityConfig.java): auth config · Controls public read access and admin write access · `src/main/java/rs/master/courses/graphQlDemo/SecurityConfig.java`

### Domain & Persistence

Core entities, repositories, and response models

- [Book](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Book.java): entity · Main book aggregate · `src/main/java/rs/master/courses/graphQlDemo/Book.java`
- [Author](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Author.java): entity · Book author domain object · `src/main/java/rs/master/courses/graphQlDemo/Author.java`
- [Category](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/Category.java): entity · Hierarchical category domain object · `src/main/java/rs/master/courses/graphQlDemo/Category.java`
- [BookRepo](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookRepo.java): repository · Book persistence and finder methods · `src/main/java/rs/master/courses/graphQlDemo/BookRepo.java`
- [AuthorRepo](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/AuthorRepo.java): repository · Author persistence and lookup methods · `src/main/java/rs/master/courses/graphQlDemo/AuthorRepo.java`
- [CategoryRepo](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/CategoryRepo.java): repository · Category persistence and tree lookups · `src/main/java/rs/master/courses/graphQlDemo/CategoryRepo.java`
- [BookInput](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookInput.java): input model · Mutation input for adding books · `src/main/java/rs/master/courses/graphQlDemo/BookInput.java`
- [BookPage](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/BookPage.java): page model · Paged book response wrapper · `src/main/java/rs/master/courses/graphQlDemo/BookPage.java`
- [SearchPage](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/SearchPage.java): result model · Cross-entity search response wrapper · `src/main/java/rs/master/courses/graphQlDemo/SearchPage.java`
- [PageInfo](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/PageInfo.java): pagination model · Paging metadata shared by responses · `src/main/java/rs/master/courses/graphQlDemo/PageInfo.java`

### Runtime & Packaging

Application bootstrap, seeding, and deployment packaging

- [Application](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/GraphQlDemoApplication.java): spring boot app · Main Spring Boot entry point · `src/main/java/rs/master/courses/graphQlDemo/GraphQlDemoApplication.java`
- [ServletInitializer](https://github.com/bourouishafsa261/graphql/blob/main/src/main/java/rs/master/courses/graphQlDemo/ServletInitializer.java): war bootstrap · Servlet-container deployment entry point · `src/main/java/rs/master/courses/graphQlDemo/ServletInitializer.java`
- [data.sql](https://github.com/bourouishafsa261/graphql/blob/main/src/main/resources/data.sql): seed data · Initial database contents · `src/main/resources/data.sql`
- [Dockerfile](https://github.com/bourouishafsa261/graphql/tree/main/Dockerfile): container build · Container packaging for deployment · `Dockerfile`
- [pom.xml](https://github.com/bourouishafsa261/graphql/blob/main/pom.xml): build config · Maven dependencies and build configuration · `pom.xml`

## Connections

- GraphQL schema → MyController: defines ops for · GraphQL operations are handled by the controller
- MyController → SecurityConfig: gated by · Admin mutations require authorization
- MyController → BookRepo: queries · Book operations read and write through repositories
- MyController → AuthorRepo: queries · Author lookups and deletion paths use repository access
- MyController → CategoryRepo: queries · Category filters and recursive traversal use repository access
- MyController → BookInput: accepts · Add-book mutation accepts structured input
- MyController → BookPage: returns · Book listing is wrapped in paged responses
- MyController → SearchPage: returns · Search results are wrapped for GraphQL delivery
- BookPage → PageInfo: includes · Paged book responses embed pagination metadata
- SearchPage → PageInfo: includes · Search responses embed pagination metadata
- BookRepo → Book: manages · Book repository persists book entities
- AuthorRepo → Author: manages · Author repository persists author entities
- CategoryRepo → Category: manages · Category repository persists category entities
- Book → Author: links to · Books reference an author
- Book → Category: links to · Books reference a category
- Application → pom.xml: built by · Application is assembled through Maven
- Application → data.sql: loads · Seed data initializes the demo database
- ServletInitializer → Application: boots · Servlet deployment starts the Spring application
- Dockerfile → Application: packages · Container image runs the application
