# acoboh/query-filter-mongodb architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Java library designed for Spring Boot applications that eases the creation–and translation–of custom filter strings into valid MongoDB queries. It supports both traditional Spring MVC with Spring Data MongoDB as well as a reactive WebFlux approach. In addition, a separate module enhances the OpenAPI/Swagger documentation.
- The examples and multiple modules (e.g., query-filter-mongodb, query-filter-mongodb-reactive, and query-filter-mongodb-openapi) indicate that the project is modular and extensible, with specific focus on dynamic query filter generation.

##### Main Components
a. Client/Consumer Layer:
– REST API Clients or UI Frontends that send query strings (using RHS Colon or LHS Bracket syntax; e.g., “author=eq:acobo”).
– They interact with the controller endpoint(s) which accept a query parameter annotated with @QFParam.

b. Controller & Service Layer:
– Controller Classes (as shown in the README) that receive the query string.
– The QueryFilter object is constructed automatically from the string filter via the custom annotation (@QFParam). This layer represents the entry point into the library’s functionality.
– Services/Repositories that eventually execute the generated MongoDB Query against MongoDB.

c. Query Filter Processing Core:
– The heart of the library that includes:
- Parsing Logic: Component that parses the input filter string (using operations like eq, gt, etc.) into an intermediary QueryFilter object.
- Annotation Processors: Classes that use annotations (e.g., @QFDefinitionClass, @QFElement, @QFDate, etc.) to build metadata for the conversion process.
- Filter Builders/Specifications: Components that translate the parsed representations into actual Spring Data MongoDB Query objects.
- Exception Handling: Exception Advisor (e.g., QFExceptionAdvisor) that intercepts malformed or blocked query parameters.

d. Integration / External Components:
– MongoDB Database: The final execution of queries against MongoDB collections.
– OpenAPI Documentation: The OpenAPI module (query-filter-mongodb-openapi) automatically enhances endpoints’ documentation by interpreting filter definitions.
– Spring Boot Container: To register beans, process annotations (e.g., @EnableQueryFilter), and configure SpEL if custom expressions are used.

##### Relationships and Interactions
- A connection from the Repository/Service layer to the MongoDB Database.
- Error handling as a separate subcomponent (e.g., Exception Advisor) that listens for errors in the parsing or execution phase and routes them accordingly.

##### Architectural Patterns and Design Principles
- Annotation-based Configuration: Highlight usage of custom annotations (like @QFDefinitionClass, @QFElement, etc.) and how the library’s processing engine uses reflection/annotation processing.
- Layered Architecture: Represent distinct layers (Client, Controller, Filter Processor, Repository, and MongoDB Database).
- Error Handling and Validation: Emphasize the exception handling layer that integrates with Spring Boot’s error processing (using advisors like QFExceptionAdvisor).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Request (REST API Client)"]:::client
    click Client "https://github.com/acoboh/query-filter-mongodb/blob/main/examples/basic-example/src/main/java/io/github/acoboh/query/filter/example/QueryFilterBasicExampleApplication.java"

    %% Controller Layer
    Controller["Controller (@QFParam)"]:::controller
    click Controller "https://github.com/acoboh/query-filter-mongodb/blob/main/examples/basic-example/src/main/java/io/github/acoboh/query/filter/example/controllers/BasicDocumentController.java"
    
    Client -->|"HTTPRequestwithQueryStringFilter"| Controller

    %% OpenAPI Enhancer (external integration)
    OpenAPI["OpenAPI Enhancer"]:::openapi
    click OpenAPI "https://github.com/acoboh/query-filter-mongodb/tree/main/query-filter-mongodb-openapi/src/main/java/io/github/acoboh/query/filter/mongodb/openapi/config"
    Controller -.->|"autodocuments"| OpenAPI

    %% Query Filter Processing Core
    subgraph "Query Filter Processing Core"
      direction TB

      subgraph "Synchronous Processing (Spring MVC)"
          SyncAnnotations["Annotations (Sync)"]:::processing
          click SyncAnnotations "https://github.com/acoboh/query-filter-mongodb/tree/main/query-filter-mongodb/src/main/java/io/github/acoboh/query/filter/mongodb/annotations"
          SyncProcessor["QueryFilter Processor (MVC)"]:::processing
          click SyncProcessor "https://github.com/acoboh/query-filter-mongodb/blob/main/query-filter-mongodb/src/main/java/io/github/acoboh/query/filter/mongodb/processor/QueryFilter.java"
          SyncAnnotations -->|"parsesfilter"| SyncProcessor
      end

      subgraph "Reactive Processing (WebFlux)"
          ReactiveAnnotations["Annotations (Reactive)"]:::processing
          click ReactiveAnnotations "https://github.com/acoboh/query-filter-mongodb/tree/main/query-filter-mongodb-reactive/src/main/java/io/github/acoboh/query/filter/mongodb/annotations"
          ReactiveProcessor["QueryFilter Processor (Reactive)"]:::processing
          click ReactiveProcessor "https://github.com/acoboh/query-filter-mongodb/blob/main/query-filter-mongodb-reactive/src/main/java/io/github/acoboh/query/filter/mongodb/processor/QueryFilter.java"
          ExceptionAdvisor["Exception Advisor"]:::processing
          click ExceptionAdvisor "https://github.com/acoboh/query-filter-mongodb/blob/main/query-filter-mongodb-reactive/src/main/java/io/github/acoboh/query/filter/mongodb/advisor/QFExceptionAdvisor.java"
          ReactiveAnnotations -->|"parsesfilter"| ReactiveProcessor
          ReactiveProcessor -->|"handlesquery"| ExceptionAdvisor
      end
    end

    %% Connections from Controller to Processing Layer
    Controller -->|"invokesSync"| SyncAnnotations
    Controller -->|"invokesReactive"| ReactiveAnnotations

    %% Service/Repository Layer
    subgraph "Service/Repository Layer"
        Service["Service Implementation"]:::service
        click Service "https://github.com/acoboh/query-filter-mongodb/blob/main/examples/basic-example/src/main/java/io/github/acoboh/query/filter/example/services/impl/BasicDocumentServiceImpl.java"
        Repository["Repository"]:::service
        click Repository "https://github.com/acoboh/query-filter-mongodb/blob/main/examples/basic-example/src/main/java/io/github/acoboh/query/filter/example/repositories/BasicDocumentRepository.java"
        Service -->|"calls"| Repository
    end

    %% Connection from Processing to Service/Repository Layer
    SyncProcessor -->|"generatesquery"| Service
    ReactiveProcessor -->|"generatesquery"| Service

    %% MongoDB Database
    MongoDB["MongoDB Database"]:::database
    Repository -->|"executesquery"| MongoDB

%% Styles
classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
classDef controller fill:#66ccff,stroke:#333,stroke-width:2px;
classDef processing fill:#ccffcc,stroke:#333,stroke-width:2px;
classDef service fill:#ff99cc,stroke:#333,stroke-width:2px;
classDef database fill:#ccccff,stroke:#333,stroke-width:2px,stroke-dasharray: 5,5;
classDef openapi fill:#ffd699,stroke:#333,stroke-width:2px;
```
