# ukrbublik/react-awesome-query-builder architecture

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

- Interactive diagram: https://gitdiagram.com/ukrbublik/react-awesome-query-builder
- Repository: https://github.com/ukrbublik/react-awesome-query-builder

## Overview

##### Project type and purpose
- This is a monorepo library/project built with pnpm workspace.
- It provides a core query-builder engine (`packages/core`) plus a UI layer (`packages/ui`) and multiple theme/skin packages (`packages/antd`, `packages/mui`, `packages/bootstrap`, `packages/fluent`, `packages/material`).
- It also includes import/export adapters (`packages/sql`), demo apps (`packages/examples`, `packages/sandbox`, `packages/sandbox_simple`, `packages/sandbox_next`), test suite (`packages/tests`), and build/config scripts.
- Purpose: let front-end and back-end teams build, render, import/export, validate complex queries in React and Node.js

##### File-structure analysis
- Top-level:
- pnpm-workspace.yaml, package.json: define workspace packages
- .github/workflows: CI steps (lint, tests, publishing)
- scripts/: shared helper scripts
- packages/: the monorepo modules
- packages/core: core query-tree logic & import/export/validation utilities (no React)
- packages/ui: core React components (`<Query>`, `<Builder>`) and vanilla widgets, CSS
- packages/{antd,mui,bootstrap,fluent,material}: each wraps `ui` to provide theme-specific widgets/config
- packages/sql: SQL adapter to import/export SQL queries
- packages/tests: Karma/Mocha tests exercising core, ui, themes
- packages/examples & sandboxes: demo apps showing library usage (React, Vite, Next.js)

##### Key README insights
- Usage patterns: import `@react-awesome-query-builder/<skin>` in your app
- Core vs UI vs theme separation: server-side only needs `core`; front-end apps need `ui` or a specific skin

a. Components:
- Monorepo root (workspace)
- Core package (`@react-awesome-query-builder/core`)
- UI package (`@react-awesome-query-builder/ui`)
- Theme packages (AntD, MUI, Bootstrap, Fluent, Material)
- SQL adapter (`@react-awesome-query-builder/sql`)
- Demo apps
- examples (TS + hot-reload + multi-skin)
- sandbox (Vite, TS, MUI)
- sandbox_simple (Vite, JS, vanilla)
- sandbox_next (Next.js, SSR API)
- Test suite (Karma, specs)
- External services & tools
- pnpm, Babel, TypeScript, Webpack/Vite, Next.js
- GitHub Actions (CI/CD)
- Codecov, CodeSandbox, Codespaces

b. Relationships & interactions:
- Core exports logic & utils → UI imports core
- UI re-exports core, provides React components + CSS
- Each skin package imports from UI and provides themed widgets/config → re-exports UI APIs
- SQL package imports core for SQL import/export
- Demo apps import either:
- a specific skin package → render query builder in different frameworks
- UI (vanilla) or core (server) only
- Tests reference core + ui + skins to validate functionality
- CI pipelines run lint/tests/build & publish to npm

c. Architectural patterns & principles:
- Monorepo with workspace packages & shared scripts/config
- Separation of concerns: core logic vs UI rendering vs theme styling
- Re-exporting pattern: theme packages re-export UI (which re-exports core)
- Demo apps as isolation environments: local dev & CI smoke
- Import/export adapters decoupled from UI
- Peer-dependencies for UI frameworks (AntD, MUI, etc.)

d. Technologies & frameworks:
- Node.js, pnpm workspace, TypeScript, Babel, Webpack, Vite, Next.js
- React, Immutable.js in UI
- Testing: Karma, Mocha/Jest, Cypress-like specs
- CI: GitHub Actions, Codecov
- CSS: SCSS modules in each package, shared CSS in UI

##### Essential architectural elements
- Monorepo root orchestrates through `pnpm-workspace.yaml`
- Core ← UI ← theme packages
- Demo apps → consume themes or UI or core
- SQL adapter ← core
- Tests exercise all layers
- CI/CD pipelines building, testing, publishing each package

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Layer
    MR["Monorepo Root"]:::root
    Scripts["Shared Scripts/Config"]:::root

    %% Core and UI
    Core["@react-awesome-query-builder/core"]:::core
    UI["@react-awesome-query-builder/ui"]:::ui

    %% Theme Packages
    subgraph "Theme Packages"
        direction TB
        AntD["AntD Skin"]:::theme
        MUI["MUI Skin"]:::theme
        BS["Bootstrap Skin"]:::theme
        Fluent["Fluent UI Skin"]:::theme
        Material["Material UI Skin"]:::theme
    end

    %% SQL Adapter
    SQL["SQL Adapter"]:::core

    %% Demo Apps
    subgraph "Demo Applications"
        direction TB
        Examples["Examples App"]:::demo
        Sandbox["Sandbox (Vite+TS+MUI)"]:::demo
        SandSimple["Sandbox Simple"]:::demo
        SandboxNext["Sandbox Next (SSR)"]:::demo
    end

    %% Test Suite and CI
    Tests["Test Suite"]:::testci
    CI["CI/CD & External Tools"]:::testci

    %% Dependencies / Flows
    UI -->|"imports"| Core
    AntD -->|"imports"| UI
    MUI -->|"imports"| UI
    BS -->|"imports"| UI
    Fluent -->|"imports"| UI
    Material -->|"imports"| UI
    SQL -->|"imports"| Core

    Examples -->|"uses skin/UI/core"| AntD
    Sandbox -->|"uses MUI skin"| MUI
    SandSimple -->|"uses UI"| UI
    SandboxNext -->|"uses core & SQL via API"| Core
    SandboxNext -->|"uses core & SQL via API"| SQL

    Tests -->|"tests layers"| Core
    Tests -->|"tests layers"| UI
    Tests -->|"tests layers"| AntD
    Tests -->|"tests layers"| MUI
    Tests -->|"tests layers"| BS
    Tests -->|"tests layers"| Fluent
    Tests -->|"tests layers"| Material
    Tests -->|"tests layers"| SQL

    MR -->|"orchestrates"| Core
    MR -->|"orchestrates"| UI
    MR -->|"orchestrates"| AntD
    MR -->|"orchestrates"| MUI
    MR -->|"orchestrates"| BS
    MR -->|"orchestrates"| Fluent
    MR -->|"orchestrates"| Material
    MR -->|"orchestrates"| SQL
    MR -->|"orchestrates"| Examples
    MR -->|"orchestrates"| Sandbox
    MR -->|"orchestrates"| SandSimple
    MR -->|"orchestrates"| SandboxNext
    MR -->|"orchestrates"| Tests
    MR -->|"runs CI/CD"| CI

    Scripts -->|"shared configs"| Core
    Scripts -->|"shared configs"| UI
    Scripts -->|"shared configs"| AntD
    Scripts -->|"shared configs"| MUI
    Scripts -->|"shared configs"| BS
    Scripts -->|"shared configs"| Fluent
    Scripts -->|"shared configs"| Material
    Scripts -->|"shared configs"| SQL

    CI -->|"runs workflows"| Tests
    CI -->|"publishes packages"| Core
    CI -->|"publishes packages"| UI
    CI -->|"publishes packages"| AntD
    CI -->|"publishes packages"| MUI
    CI -->|"publishes packages"| BS
    CI -->|"publishes packages"| Fluent
    CI -->|"publishes packages"| Material
    CI -->|"publishes packages"| SQL

    %% Click Events
    click MR "https://github.com/ukrbublik/react-awesome-query-builder/blob/master/pnpm-workspace.yaml"
    click Scripts "https://github.com/ukrbublik/react-awesome-query-builder/blob/master/scripts/clean.sh"
    click Core "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/core/"
    click UI "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/ui/"
    click AntD "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/antd/"
    click MUI "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/mui/"
    click BS "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/bootstrap/"
    click Fluent "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/fluent/"
    click Material "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/material/"
    click SQL "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sql/"
    click Examples "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/examples/"
    click Sandbox "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sandbox/"
    click SandSimple "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sandbox_simple/"
    click SandboxNext "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sandbox_next/"
    click Tests "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/tests/"
    click CI "https://github.com/ukrbublik/react-awesome-query-builder/tree/master/.github/workflows/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef ui fill:#90EE90,stroke:#000,stroke-width:1px
    classDef theme fill:#FFA500,stroke:#000,stroke-width:1px
    classDef demo fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef testci fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef root fill:#F0F0F0,stroke:#000,stroke-width:1px
```
