# phonepe/query-dsl architecture

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

- Interactive diagram: https://gitdiagram.com/phonepe/query-dsl
- Repository: https://github.com/phonepe/query-dsl

## Overview

##### Main Components
- Filter Models/API Layer: Represent the core classes that model various filter types. This includes packages such as:
- general (e.g., EqualsFilter, NotEqualsFilter, InFilter, NotInFilter, ExistsFilter, MissingFilter, ContainsFilter, AnyFilter, GenericFilter)
- numeric (e.g., BetweenFilter, GreaterThanFilter, GreaterEqualFilter, LessThanFilter, LessEqualFilter, NumericBinaryFilter)
- logical (e.g., AndFilter, OrFilter, NotFilter)
- string (e.g., StringStartsWithFilter, StringEndsWithFilter, StringRegexMatchFilter)
- Visitor Pattern Implementation: The FilterVisitor interface and its abstract implementation (AbstractFilterVisitor) – this is key to how filter evaluation, serialization, or transformation is handled.
- JSON Serialization/Deserialization: Use of Jackson (as described in the README) which enables converting Filter objects to/from JSON. While not a separate package, this is an important integration point in the design.
- Testing Components: The test packages and JSON resources that validate the DSL functionality and ensure correct behavior through unit tests such as FilterCounterTest, FilterEvalTest, etc.

##### Relationships and Interactions
- The Filter model classes are the core representations that define the DSL. They are composed to form more complex queries (for example, composing simple filters into an AndFilter or OrFilter).
- The Visitor Pattern enables separation of concerns: different concrete visitors (like a DBQueryVisitor mentioned in the README example or an evaluation visitor) “visit” the filter objects and execute appropriate processing logic as per the filter type.
- JSON serialization/deserialization acts as the bridge for external representations (often used for storing or exchanging filter definitions) and the internal Java object models.

##### Architectural Patterns and Design Principles
- Modularity: The clear separation between different filter types (general, logical, numeric, string) implies a design that is easily extendable.
- Visitor Pattern: This design pattern is central to the processing architecture – by implementing the FilterVisitor interface, various operations can be plugged in without changing the filter classes themselves.
- Type Safety: The DSL is built around strongly typed filter classes (facilitated by builder patterns in Java) to catch configuration issues during compile time.

##### Relevant Technologies
- Java 17: The project requires Java 17 or higher.
- Maven: The build tool (with a pom.xml) dictates project dependencies and build configuration.
- Jackson: Used for JSON serialization/deserialization – a major integration point as seen in the examples in the README.
- JUnit (or similar): Underlying the test directory is a standard testing framework for unit tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Filter Models"
        GF["General Filters"]:::filterModels
        LF["Logical Filters"]:::filterModels
        NF["Numeric Filters"]:::filterModels
        SF["String Filters"]:::filterModels
    end

    FV["FilterVisitor Interface"]:::visitor
    AFV["AbstractFilterVisitor"]:::visitor
    JSON["JSON Serializer/Deserializer"]:::integration
    TEST["Test Cases"]:::testing

    GF -->|"accept() call"| FV
    LF -->|"accept() call"| FV
    NF -->|"accept() call"| FV
    SF -->|"accept() call"| FV

    GF -->|"accept() call"| AFV
    LF -->|"accept() call"| AFV
    NF -->|"accept() call"| AFV
    SF -->|"accept() call"| AFV

    GF <==>|"JSON conversion"| JSON
    LF <==>|"JSON conversion"| JSON
    NF <==>|"JSON conversion"| JSON
    SF <==>|"JSON conversion"| JSON

    TEST -->|"verifies"| GF
    TEST -->|"verifies"| LF
    TEST -->|"verifies"| NF
    TEST -->|"verifies"| SF
    TEST -->|"verifies"| FV
    TEST -->|"verifies"| AFV
    TEST -->|"verifies"| JSON

    click GF "https://github.com/phonepe/query-dsl/tree/main/src/main/java/com/phonepe/commons/query/dsl/general"
    click LF "https://github.com/phonepe/query-dsl/tree/main/src/main/java/com/phonepe/commons/query/dsl/logical"
    click NF "https://github.com/phonepe/query-dsl/tree/main/src/main/java/com/phonepe/commons/query/dsl/numeric"
    click SF "https://github.com/phonepe/query-dsl/tree/main/src/main/java/com/phonepe/commons/query/dsl/string"
    click FV "https://github.com/phonepe/query-dsl/blob/main/src/main/java/com/phonepe/commons/query/dsl/FilterVisitor.java"
    click AFV "https://github.com/phonepe/query-dsl/blob/main/src/main/java/com/phonepe/commons/query/dsl/AbstractFilterVisitor.java"
    click JSON "https://github.com/phonepe/query-dsl/tree/main/src/test/resources/filters"
    click TEST "https://github.com/phonepe/query-dsl/tree/main/src/test/java/com/phonepe/commons/query/dsl"

    classDef filterModels fill:#AED6F1,stroke:#2980B9,stroke-width:2px;
    classDef visitor fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef integration fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef testing fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
