# acoboh/query-filter-jpa architecture

> Architecture diagram of the GitHub repository acoboh/query-filter-jpa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acoboh/query-filter-jpa
- Repository: https://github.com/acoboh/query-filter-jpa

## Overview

Based on our analysis of both the file tree and the README, the project is a Java library for dynamic query filtering in JPA (with special support for Spring Boot 2/3) that lets developers define filters via annotations and then auto-generate JPA Specification objects. It is also split into several modules – the core filtering module (e.g., query-filter-jpa and query-filter-jpa-3 for Spring Boot 3), an OpenAPI integration module (e.g., query-filter-jpa-openapi and query-filter-jpa-openapi-3), several example projects (both a basic example and one with Docker support), and a collection of tests and documentation. The goal is to provide an intuitive, annotation-driven way to create dynamic queries without needing to build JPA Specifications manually.

##### Project Type and Purpose
- The project is a library (with example applications) designed to simplify filtering of JPA queries by allowing users to define filter definitions using custom annotations.
- It integrates with Spring Boot (with distinct modules for Boot 2 and Boot 3), and it includes an OpenAPI module that auto-documents the filter APIs.

##### Analyzing the File Structure
- The top-level directories include configuration files (such as .github/** for CI/CD), documentation (doc/), examples (with two variants in the examples directory), and multiple modules with dedicated functionality (query-filter-jpa, query-filter-jpa-3, query-filter-jpa-openapi, etc.).
- Inside each module, the package structure is organized under “io/github/acoboh/query/…” which further divides the code into subpackages such as “filter”, “filter/jpa”, “filter/jpa/annotations”, “filter/jpa/processor”, “filter/jpa/exceptions”, etc.
- The extensive file tree for query-filter-jpa and its related modules indicates a clear separation of core processing (converter, processor, definition handling), exception management, and platform-specific contributions (JPA, OpenAPI).

##### Key Components of the Architecture
A. Client and API Layer
- REST Controllers (as shown in the examples – e.g., PostRestController) that receive HTTP requests containing query parameters for filtering.
- The query parameters can be provided in different syntaxes (RHS colon and LHS bracket formats).
B. Query Filter Library Core
- Annotations: Custom annotations such as @QFDefinitionClass, @QFElement, @QFDate, etc., which define how filtering is applied.
- Filter Definition Classes: Classes that capture the filterable fields (e.g., PostFilterDef) and guide the filter processing.
- Filter Processor: Components (located in the jpa/processor subpackages) that parse input query parameters and construct the corresponding JPA Specification objects.
- Exception Handling: A set of custom exceptions (grouped under query-filter/jpa/exceptions) that help manage errors during filter parsing and execution.
- Converter and Resolutors: Components that convert query parameters into the corresponding model types and resolve the correct operations (in packages like converters and operations/resolutors).
C. Integration with JPA Repositories
- Repositories extending JpaSpecificationExecutor that integrate the query filter output into dynamic JPA queries.
D. OpenAPI Integration Module
- A separate module (query-filter-jpa-openapi[(-3)]) that auto-generates API documentation using the filter definitions.
- This module hooks into Spring Boot’s auto-configuration to include filter details in the Swagger-UI.
E. Example Applications and Supporting Infrastructure
- The examples directory contains sample Spring Boot applications demonstrating the usage of the library.
- Docker-compose and scripts (in the examples/docker and similar directories) show how to run the application in various deployment environments.

##### Architectural Patterns and Design Principles
- Modular Design: The separation of core filtering functionality, Spring Boot integration, and OpenAPI support into different modules.
- Annotation-driven Configuration: The heavy use of custom annotations to simplify filter definition.
- Separation of Concerns: Controllers handle HTTP and parameter passing; processing components convert filter parameters to Specification objects; repositories execute the queries.
- Extensibility: The design supports custom converters, resolutors, and exception management, which assist in advanced filtering features like arrays, JSON fields, and sorting.

##### Final Reminder
- Be as detailed as possible – don’t shy away from breaking the system into many components if necessary.
- Capturing the essence: the transformation of filter query parameters (via annotations and filter definitions) into dynamic JPA queries.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    client["Client"]:::api

    %% Client & API Layer
    subgraph "Client & API Layer"
        rest["REST Controller"]:::api
    end

    %% Core Query Filter Library
    subgraph "Core Query Filter Library"
        customAnn["Custom Annotations"]:::core
        filterDef["Filter Definition Classes"]:::core
        processor["Filter Processor"]:::core
        exceptions["Exception Handling"]:::core
        converters["Converters"]:::core
        resolvers["Resolvers"]:::core
    end

    %% Integration Modules
    subgraph "Integration Modules"
        jpa["JPA Repository Integration"]:::integration
        subgraph "OpenAPI Integration"
            openapiCustom["OpenAPI Customiser"]:::integration
            openapiAuto["OpenAPI Autoconfigurer"]:::integration
        end
    end

    %% Deployment/Examples
    subgraph "Deployment/Examples"
        exampleApp["Spring Boot Example App"]:::deployment
        docker["Docker Compose"]:::deployment
    end

    %% Database Node
    database["Database"]:::integration

    %% Connections
    client -->|"HTTP_Request"| rest
    rest -->|"calls"| processor
    customAnn -->|"assist"| processor
    filterDef -->|"guide"| processor
    processor -->|"uses"| exceptions
    processor -->|"converts_using"| converters
    processor -->|"resolves_using"| resolvers
    processor -->|"executes_query"| jpa
    jpa -->|"fetches_from"| database
    filterDef -->|"auto-documents"| openapiCustom
    customAnn -->|"auto-documents"| openapiAuto

    %% Styles
    classDef api fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef integration fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef deployment fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;

    %% Click Events
    click rest "https://github.com/acoboh/query-filter-jpa/blob/main/examples/basic-example-sb-3/src/main/java/io/github/acoboh/query/filter/example/controllers/PostRestController.java"
    click filterDef "https://github.com/acoboh/query-filter-jpa/blob/main/examples/basic-example-sb-3/src/main/java/io/github/acoboh/query/filter/example/filterdef/PostFilterDef.java"
    click customAnn "https://github.com/acoboh/query-filter-jpa/tree/main/query-filter-jpa-3/src/main/java/io/github/acoboh/query/filter/jpa/annotations/"
    click processor "https://github.com/acoboh/query-filter-jpa/tree/main/query-filter-jpa-3/src/main/java/io/github/acoboh/query/filter/jpa/processor/"
    click exceptions "https://github.com/acoboh/query-filter-jpa/tree/main/query-filter-jpa-3/src/main/java/io/github/acoboh/query/filter/jpa/exceptions/"
    click converters "https://github.com/acoboh/query-filter-jpa/tree/main/query-filter-jpa-3/src/main/java/io/github/acoboh/query/filter/jpa/converters/"
    click resolvers "https://github.com/acoboh/query-filter-jpa/tree/main/query-filter-jpa-3/src/main/java/io/github/acoboh/query/filter/jpa/operations/resolutors/"
    click jpa "https://github.com/acoboh/query-filter-jpa/blob/main/examples/basic-example-sb-3/src/main/java/io/github/acoboh/query/filter/example/repositories/PostBlogRepository.java"
    click openapiCustom "https://github.com/acoboh/query-filter-jpa/blob/main/query-filter-jpa-openapi-3/src/main/java/io/github/acoboh/query/filter/jpa/openapi/config/OpenApiCustomiserImpl.java"
    click openapiAuto "https://github.com/acoboh/query-filter-jpa/blob/main/query-filter-jpa-openapi-3/src/main/java/io/github/acoboh/query/filter/jpa/openapi/config/QueryFilterOpenApiAutoconfigurer.java"
    click exampleApp "https://github.com/acoboh/query-filter-jpa/tree/main/examples/basic-example-sb-3/"
    click docker "https://github.com/acoboh/query-filter-jpa/blob/main/examples/docker/docker-compose.yml"
```
