# trendyol/es-query-builder architecture

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

- Interactive diagram: https://gitdiagram.com/trendyol/es-query-builder
- Repository: https://github.com/trendyol/es-query-builder

## Overview

##### Project Type and Purpose
- This is a Go-based library (es-query-builder) for programmatically constructing Elasticsearch DSL queries.
- It is _not_ a standalone server or web application; it provides a fluent, composable API in Go (“es” package) that produces JSON query/aggregation objects to be sent to an Elasticsearch cluster.

##### File Structure
- **es/**: the core package. Contains subpackages or files for:
- Queries (bool, term, match, range, etc.)
- Aggregations (avg, sum, terms, nested, multi-terms, etc.)
- Condition builders (if, constant_score)
- Enums (collect-mode, sort orders, script languages, etc.)
- **example/**: a minimal Go program showing how a consumer uses the library.
- **benchmarks/**: performance tests comparing this library against vanilla Go maps and other libraries.
- **internal/integration-test/**: a suite that:
- Spins up an Elasticsearch container
- Defines document models & repositories
- Loads test data
- Runs true end-to-end queries against ES
- **.github/** + CI workflows: GitHub Actions for build/test, security checks, releases.
- **Makefile**, **goreleaser.yml**: build and release tooling.
- **test/assert/**: small assertion helpers.

##### README for Additional Insights
- Confirms the library’s goal: minimal overhead, fluent API to build JSON DSL.
- Shows sample usage (Bool().Must(…).Aggs(…)), emphasizing the fluent-builder pattern.
- Mentions benchmarks and integration tests—key parts of the architecture.

a. Main Components
- Consumer Code (example or any Go application)
- es-query-builder Library (“es” package)
- Query Builder Core
- Aggregations Module
- Conditions Module
- Enums Module
- Benchmarks Suite
- Integration Test Suite
- Docker/Elasticsearch Container
- Model & Repository Layer
- Test Data Provider
- CI/CD Pipelines (GitHub Actions)
b. Relationships & Interactions
- Consumer → calls → es Library → returns → JSON DSL
- Consumer → (via HTTP client) → Elasticsearch Cluster
- Benchmarks & Integration Tests → import → es Library
- Integration Tests → orchestrate → Docker container
- CI Workflows → trigger → build, test, benchmark, release
c. Architectural Patterns & Principles
- Fluent-Builder Pattern: chainable methods producing immutable query structures
- Composite Pattern: query/aggregation nodes forming a tree
- Separation of Concerns: core builder (es/) vs. consumer code vs. test harness
- Internal Packages: hide test-only utilities (in internal/)
d. Key Technologies & Frameworks
- Go Modules (go.mod)
- Docker (for integration Elasticsearch)
- Go Testing & Benchmarking
- GitHub Actions (CI/CD)
- goreleaser & Makefile (release automation)

##### Detailed Architectural Elements to Capture
- The internal package boundary (tests under internal/integration-test) to indicate “not for public consumption.”
- The bench-marking harness reading benchmark files under benchmarks/tests.
- CI workflows invoking Makefile targets (test, bench, release).
- Example code as a consumer stub showing typical usage.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Consumer Layer
    subgraph "Consumer Code"
        Consumer["Go Application\n(example/example.go)"]:::consumer
    end

    %% Core Library
    subgraph "es-query-builder Library"
        direction TB
        BaseCore["Query Builder Core"]:::core
        QueryTypes["Query Types Module"]:::module
        Aggs["Aggregations Module"]:::module
        Conditions["Conditions Module"]:::module
        Enums["Enums Module"]:::module
    end

    %% Benchmarks Suite
    subgraph "Benchmark Suite"
        Benchmarks["Benchmark Tests"]:::test
    end

    %% Integration Test Suite
    subgraph "Integration Test Suite"
        direction TB
        Container["ES Container Orchestration"]:::test
        Models["Models"]:::test
        Repos["Repositories"]:::test
        DataProvider["Test Data Provider"]:::test
        IntTests["Integration Tests"]:::test
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        Workflows["GitHub Actions Workflows"]:::ci
        Release["Makefile & goreleaser.yml"]:::ci
    end

    %% External Systems
    subgraph "External Systems"
        ESCluster["Elasticsearch Cluster"]:::external
    end

    %% Connections
    Consumer -->|"uses"| BaseCore
    BaseCore -->|"provides APIs to"| QueryTypes
    BaseCore -->|"provides APIs to"| Aggs
    BaseCore -->|"provides APIs to"| Conditions
    BaseCore -->|"provides APIs to"| Enums

    Consumer -->|"generates JSON DSL"| JSON["JSON DSL"]:::data
    JSON -->|"HTTP"| ESCluster

    Benchmarks -->|"imports"| BaseCore
    Benchmarks -->|"benchmarks modules"| QueryTypes
    Benchmarks -->|"benchmarks modules"| Aggs

    IntTests -->|"uses orchestration"| Container
    IntTests -->|"uses models"| Models
    IntTests -->|"uses repos"| Repos
    IntTests -->|"uses data provider"| DataProvider
    IntTests -->|"executes against"| ESCluster

    Workflows -->|"trigger"| Benchmarks
    Workflows -->|"trigger"| IntTests
    Workflows -->|"trigger"| Release

    %% Click Events
    click Consumer "https://github.com/trendyol/es-query-builder/blob/main/example/example.go"
    click BaseCore "https://github.com/trendyol/es-query-builder/blob/main/es/base_query.go"
    click BaseCore "https://github.com/trendyol/es-query-builder/blob/main/es/types.go"
    click QueryTypes "https://github.com/trendyol/es-query-builder/blob/main/es/bool_query.go"
    click QueryTypes "https://github.com/trendyol/es-query-builder/blob/main/es/term_query.go"
    click QueryTypes "https://github.com/trendyol/es-query-builder/blob/main/es/match_query.go"
    click QueryTypes "https://github.com/trendyol/es-query-builder/blob/main/es/range.go"
    click QueryTypes "https://github.com/trendyol/es-query-builder/blob/main/es/nested_query.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_avg.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_sum.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_terms.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_nested.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_multi_terms.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_extended_stats.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_cardinality.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_stats.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_max.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_min.go"
    click Aggs "https://github.com/trendyol/es-query-builder/blob/main/es/aggregation_order.go"
    click Conditions "https://github.com/trendyol/es-query-builder/blob/main/es/condition/if.go"
    click Conditions "https://github.com/trendyol/es-query-builder/blob/main/es/constant_score_query.go"
    click Enums "https://github.com/trendyol/es-query-builder/tree/main/es/enums"
    click Benchmarks "https://github.com/trendyol/es-query-builder/tree/main/benchmarks/tests"
    click Container "https://github.com/trendyol/es-query-builder/blob/main/internal/integration-test/container/elasticsearch.go"
    click Models "https://github.com/trendyol/es-query-builder/tree/main/internal/integration-test/model"
    click Repos "https://github.com/trendyol/es-query-builder/tree/main/internal/integration-test/repository"
    click DataProvider "https://github.com/trendyol/es-query-builder/tree/main/internal/integration-test/test-data-provider"
    click IntTests "https://github.com/trendyol/es-query-builder/tree/main/internal/integration-test/tests"
    click Workflows "https://github.com/trendyol/es-query-builder/blob/main/.github/workflows/build-test.yml"
    click Workflows "https://github.com/trendyol/es-query-builder/blob/main/.github/workflows/release.yml"
    click Workflows "https://github.com/trendyol/es-query-builder/blob/main/.github/workflows/scorecard.yml"
    click Workflows "https://github.com/trendyol/es-query-builder/blob/main/.github/workflows/security-gates.yml"
    click Release "https://github.com/trendyol/es-query-builder/tree/main/Makefile"
    click Release "https://github.com/trendyol/es-query-builder/blob/main/goreleaser.yml"
    click Assertion "https://github.com/trendyol/es-query-builder/blob/main/test/assert/assert.go"

    %% Styles
    classDef consumer fill:#DFF8E0,stroke:#2E7D32,stroke-width:2px
    classDef core fill:#E3F2FD,stroke:#1565C0,stroke-width:2px
    classDef module fill:#FFF8E1,stroke:#F9A825,stroke-width:2px
    classDef test fill:#FCE4EC,stroke:#C2185B,stroke-width:2px
    classDef ci fill:#E8F5E9,stroke:#388E3C,stroke-width:2px
    classDef external fill:#ECEFF1,stroke:#455A64,stroke-width:2px
    classDef data fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px
```
