# timauzi/cqql-es architecture

> Architecture diagram of the GitHub repository timauzi/cqql-es, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timauzi/cqql-es
- Repository: https://github.com/timauzi/cqql-es

## Overview

##### Project Type and Purpose
- Type: An Elasticsearch plugin (Java‐based) that implements “Commuting Quantum” Boolean query semantics using Symja (Matheclipse).
- Purpose: Hook into Elasticsearch’s query pipeline, parse incoming JSON queries under a new “commuting_quantum” clause, transform them according to Boolean‐algebra laws via Symja, then execute them through Elasticsearch’s search subsystem.

##### File Structure
- build.gradle at root of search-cqql indicates a Gradle‐built Java project.
- src/main/java/org/elasticsearch/plugin/query/CQQLPlugin.java – Entry point: registers the plugin.
- src/main/java/org/elasticsearch/index/query/CommutingQuantumQueryBuilder.java & AtomicQueryBuilderName.java – JSON → internal Query objects.
- src/main/java/org/elasticsearch/index/search/CommutingQuantumQuery.java – Wraps the rewriting logic.
- CommutingQuantumWeight & CommutingQuantumScorer – Integrate with Lucene scoring.
- libs/matheclipse/*.jar – Third-party Symja library, used for symbolic simplification.
- plugin-metadata/plugin-security.policy – JVM security policy granting file‐system access for Symja temp files.

##### Extract Architecture Insights from the README
- The plugin replaces “bool” DSL with “commuting_quantum” and enforces Boolean‐algebra equivalences before execution.
- Relies on Symja only for symbolic transformations, then feeds results back into Elasticsearch’s native engine.
- Loaded at runtime via elasticsearch-plugin install; no external microservices.

##### Main Components
a. External Inputs:
– Client JSON Query with “commuting_quantum” clause.
b. Elasticsearch Core:
– REST layer → Query DSL parser → Plugin registry.
c. CQQL Plugin Module:
– CQQLPlugin (registers builder/rewrite phases)
– CommutingQuantumQueryBuilder (parses JSON → AST)
– AtomicQueryBuilderName (maps atomic query types)
– Symja Library (matheclipse jars)
– CommutingQuantumQuery → rewrite() uses Symja to enforce algebra laws
– CommutingQuantumWeight → compute weight
– CommutingQuantumScorer → score documents
d. Lucene Search Engine (underneath ES): executes the rewritten query.
e. Data Flow: results back to client.

##### Relationships & Interactions
1. Client → ES REST API
2. REST API → Query Parser → CommutingQuantumQueryBuilder
3. QueryBuilder → builds CommutingQuantumQuery instance
4. CommutingQuantumQuery.rewrite() → invokes Symja symbol engine
5. Rewritten query → CommutingQuantumWeight → CommutingQuantumScorer
6. Lucene executes scorer → hits
7. Results → client
- Plugin registration during node startup.

##### Architectural Patterns & Design Principles
- Extension Point Pattern: implements Elasticsearch’s Plugin interface and QuerySpec for modular integration.
- Builder Pattern: QueryBuilder classes create Query objects.
- Strategy Pattern: custom Weight/Scorer for scoring strategy.
- Separation of Concerns: Symja only for symbolic logic, ES handles indexing & scoring.

##### Technologies & Frameworks
- Java + Gradle
- Elasticsearch Plugin API (v7.10.2)
- Lucene Query/Weight/Scorer API
- Symja (Matheclipse) – jars under libs/
- JVM Security Policy for file‐system access

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Client
    Client["Client JSON Query"]:::external

    %% ES Core Layer
    subgraph "Elasticsearch Core"
        direction TB
        ESREST["ES REST API"]:::es
        QueryParser["Query Parser"]:::es
        PluginRegistry["Plugin Registry"]:::es
    end

    %% Plugin Module Layer
    subgraph "CQQL Plugin Module"
        direction TB
        CQQLPlugin["CQQLPlugin"]:::plugin
        CommutingQuantumQueryBuilder["CommutingQuantumQueryBuilder"]:::plugin
        AtomicQueryBuilderName["AtomicQueryBuilderName"]:::plugin
        CommutingQuantumQuery["CommutingQuantumQuery"]:::plugin
        CommutingQuantumWeight["CommutingQuantumWeight"]:::plugin
        CommutingQuantumScorer["CommutingQuantumScorer"]:::plugin
        JVMPolicy["JVM Security Policy"]:::plugin
    end

    %% External Library Layer
    subgraph "External Library"
        direction TB
        Symja["Symja (Matheclipse)"]:::lib
    end

    %% Lucene Layer
    subgraph "Lucene Search Engine"
        direction TB
        LuceneExe["Lucene Engine"]:::lucene
    end

    %% Build Config
    BuildGradle["build.gradle"]:::es

    %% Data Flow
    Client -->|"HTTP Request"| ESREST
    ESREST -->|"parse request"| QueryParser
    QueryParser -->|"lookup 'commuting_quantum'"| PluginRegistry
    PluginRegistry -.->|"registers plugin"| CQQLPlugin
    CQQLPlugin -. startup .-> PluginRegistry

    QueryParser -->|"build query"| CommutingQuantumQueryBuilder
    CommutingQuantumQueryBuilder -->|"maps atomic names"| AtomicQueryBuilderName
    CommutingQuantumQueryBuilder -->|"creates query"| CommutingQuantumQuery
    CommutingQuantumQuery -->|"rewrite() uses"| Symja
    Symja -->|"simplified AST"| CommutingQuantumQuery
    CommutingQuantumQuery -->|"to Weight"| CommutingQuantumWeight
    CommutingQuantumWeight -->|"to Scorer"| CommutingQuantumScorer
    CommutingQuantumScorer -->|"execute scoring"| LuceneExe
    LuceneExe -->|"hits"| ESREST
    ESREST -->|"HTTP Response"| Client

    %% Configuration & Policy
    BuildGradle -. loads config .-> CQQLPlugin
    JVMPolicy -. security rules .-> Symja

    %% Click Events
    click CQQLPlugin "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/plugin/query/CQQLPlugin.java"
    click CommutingQuantumQueryBuilder "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/index/query/CommutingQuantumQueryBuilder.java"
    click AtomicQueryBuilderName "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/index/query/AtomicQueryBuilderName.java"
    click CommutingQuantumQuery "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/index/search/CommutingQuantumQuery.java"
    click CommutingQuantumWeight "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/index/search/CommutingQuantumWeight.java"
    click CommutingQuantumScorer "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/java/org/elasticsearch/index/search/CommutingQuantumScorer.java"
    click Symja "https://github.com/timauzi/cqql-es/tree/main/search-cqql/libs/matheclipse/"
    click JVMPolicy "https://github.com/timauzi/cqql-es/blob/main/search-cqql/src/main/plugin-metadata/plugin-security.policy"
    click BuildGradle "https://github.com/timauzi/cqql-es/blob/main/search-cqql/build.gradle"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef es fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#bfb,stroke:#333,stroke-width:1px
    classDef lib fill:#ffb,stroke:#333,stroke-width:1px
    classDef lucene fill:#ffb,stroke:#333,stroke-width:1px
```
