# ryanwelcher/advanced-query-loop architecture

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

- Interactive diagram: https://gitdiagram.com/ryanwelcher/advanced-query-loop
- Repository: https://github.com/ryanwelcher/advanced-query-loop

## Overview

##### Project type and purpose
- This is a WordPress plugin (“Advanced Query Loop”) that provides an enhanced variation of the core Gutenberg Query Loop block.
- It consists of a PHP “backend” that hooks into WordPress, generates modified query parameters, and registers server-side assets, plus a React/JavaScript “frontend” that extends the block editor UI.

##### File structure
- Top level:
- index.php – main plugin bootstrap
- composer.json / package.json – PHP and JavaScript dependency manifests
- webpack.config.js – JavaScript build configuration
- .github / tests / phpunit.xml – CI and testing setup
- includes/ directory (PHP):
- Query_Params_Generator.php – central class that assembles WP_Query args
- Traits/ – reusable filters (Date_Query, Meta_Query, Tax_Query, etc.)
- enqueues.php – registers PHP assets and block scripts/styles
- query-loop.php, taxonomy.php, utilities.php – support functions
- src/ directory (JS):
- components/ – individual React controls (post-include, exclude, order, pagination toggle, etc.)
- slots/ – slot fills for injecting controls into the Query Loop sidebar
- hooks/ – custom hooks (useDebouncedInputValue)
- legacy-controls/ – polyfills for older Gutenberg versions
- utils/variations/ – block variation registration and default settings
- tests/ – PHPUnit tests for PHP classes
- .github/workflows – automated linting, testing, release.

##### Architectural insights from README
- Plugin adds new Query Loop block variation with additional controls for taxonomy, post-meta, date, pagination, etc.
- It is extensible (see extending-aql.md) – third-party code can hook into the generator or add custom traits.

##### Main components and their relationships
A. WordPress Core
- Provides block editor environment, REST API endpoints, and WP_Query engine.
B. Plugin Bootstrap (index.php)
- Registers block variation, loads includes/enqueues, hooks into render process.
C. PHP Query_Params_Generator
- Combines enabled traits based on block attributes to produce final WP_Query args.
D. Traits (Date_Query, Meta_Query, etc.)
- Encapsulate individual query modifications; attached dynamically to the generator.
E. JavaScript Block Variation
- React code in src/variations registers a new block type with custom attribute schema.
F. Editor UI Components
- Each control (components/*) reads/writes specific block attributes.
- slots/* inject those controls into the Query Loop sidebar via Gutenberg Slot/Fill API.
G. Build System
- webpack bundles React code into editor.js and front-end.js.
- composer and npm manage PHP/JS dependencies.
H. Tests & CI
- PHPUnit runs tests on PHP classes.
- GitHub Actions orchestrates lint, test, and release.

##### Architectural patterns and design principles
- Plugin modularity via Traits – each query feature is decoupled.
- Separation of Concerns – PHP handles data generation and render; JS handles editor configuration and UI.
- Gutenberg Slot/Fill pattern for non-intrusive UI extension.
- Block variation registration to reuse core block behavior with extra attributes.

##### Final checklist
- All main components (WordPress core, plugin bootstrap, PHP classes, React UI, build & CI).
- Clear data flows: user input → block editor → server render → front-end output.
- Technology labels: PHP, WP_Query, React, Gutenberg Slot/Fill, webpack, PHPUnit, GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "WordPress Core"
        BlockEditor["Block Editor UI"]:::core
        RESTAPI["REST API"]:::core
        WPQuery["WP_Query Engine"]:::core
        Database[(Database)]:::core
    end

    subgraph "PHP Backend"
        Index["Plugin Bootstrap (index.php)"]:::php
        Enqueues["Asset & Script Registration"]:::php
        Generator["Query_Params_Generator"]:::php
        subgraph "Traits"
            TraitDate["Date_Query"]:::trait
            TraitMeta["Meta_Query"]:::trait
            TraitTax["Tax_Query"]:::trait
            TraitInclude["Include_Posts"]:::trait
            TraitExcludeCurr["Exclude_Current"]:::trait
            TraitExcludeTax["Exclude_Taxonomies"]:::trait
            TraitMultiple["Multiple_Posts"]:::trait
            TraitParent["Post_Parent"]:::trait
            TraitDisablePag["Disable_Pagination"]:::trait
        end
        SupportQueryLoop["query-loop.php"]:::php
        SupportTax["taxonomy.php"]:::php
        SupportUtil["utilities.php"]:::php
    end

    subgraph "JS Frontend"
        Webpack["webpack.config.js"]:::tool
        VariationsEntry["variations/index.js"]:::js
        ControlsSetup["variations/controls.js"]:::js
        subgraph "Slot Fills"
            SlotMain["aql-controls.js"]:::js
            SlotInherited["aql-controls-inherited-query.js"]:::js
            SlotLegacy["aql-legacy-controls.js"]:::js
        end
        subgraph "React Components"
            CPostInclude["post-include-controls.js"]:::component
            CPostExclude["post-exclude-controls.js"]:::component
            CTaxQuery["taxonomy-query-control.js"]:::component
            CSingleTax["single-taxonomy-control.js"]:::component
            CPostMetaQuery["post-meta-query-controls.js"]:::component
            CPostMeta["post-meta-control.js"]:::component
            CPostDate["post-date-query-controls.js"]:::component
            CPostOrder["post-order-controls.js"]:::component
            CPostOffset["post-offset-controls.js"]:::component
            CPostCount["post-count-controls.js"]:::component
            CMultiplePost["multiple-post-select.js"]:::component
            CExcludeTax["exclude-taxonomies.js"]:::component
            CPaginationToggle["pagination-toggle.js"]:::component
            CChildItemsToggle["child-items-toggle.js"]:::component
            CIcons["icons.js"]:::component
        end
        HookDebounce["useDebouncedInputValue.js"]:::js
        PolyfillPreGB["pre-gb-19.js"]:::js
        UtilJS["utils/index.js"]:::js
    end

    subgraph "CI & Build"
        Npm["npm (package.json)"]:::tool
        Composer["composer.json"]:::tool
        GitHubActions["GitHub Actions"]:::ci
        PHPUnit["PHPUnit Tests"]:::ci
    end

    %% Data Flows
    BlockEditor -->|"injects via Slot/Fill"| SlotMain
    BlockEditor -->|"injects via Slot/Fill"| SlotInherited
    BlockEditor -->|"injects via Slot/Fill"| SlotLegacy
    VariationsEntry -->|"registers block variation"| BlockEditor
    Webpack -->|"bundles"| VariationsEntry
    Webpack -->|"bundles"| ControlsSetup
    CPostInclude -->|reads/writes| BlockEditor
    CPostExclude -->|reads/writes| BlockEditor
    CTaxQuery -->|reads/writes| BlockEditor
    CSingleTax -->|reads/writes| BlockEditor
    CPostMetaQuery -->|reads/writes| BlockEditor
    CPostMeta -->|reads/writes| BlockEditor
    CPostDate -->|reads/writes| BlockEditor
    CPostOrder -->|reads/writes| BlockEditor
    CPostOffset -->|reads/writes| BlockEditor
    CPostCount -->|reads/writes| BlockEditor
    CMultiplePost -->|reads/writes| BlockEditor
    CExcludeTax -->|reads/writes| BlockEditor
    CPaginationToggle -->|reads/writes| BlockEditor
    CChildItemsToggle -->|reads/writes| BlockEditor
    CIcons -->|provides icons| BlockEditor

    BlockEditor -->|"user updates attributes"| Generator
    Index -->|"hook into render"| Generator
    Generator -->|"calls"| WPQuery
    WPQuery -->|"queries"| Database
    Generator -->|"uses"| TraitDate
    Generator -->|"uses"| TraitMeta
    Generator -->|"uses"| TraitTax
    Generator -->|"uses"| TraitInclude
    Generator -->|"uses"| TraitExcludeCurr
    Generator -->|"uses"| TraitExcludeTax
    Generator -->|"uses"| TraitMultiple
    Generator -->|"uses"| TraitParent
    Generator -->|"uses"| TraitDisablePag
    Generator -->|"calls"| SupportQueryLoop
    Generator -->|"calls"| SupportTax
    Generator -->|"calls"| SupportUtil

    Npm -->|"manages"| Webpack
    Composer -->|"manages"| Index
    GitHubActions -->|"runs"| PHPUnit

    %% Click Events
    click Index "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/index.php"
    click Enqueues "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/enqueues.php"
    click Generator "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Query_Params_Generator.php"
    click TraitDate "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Date_Query.php"
    click TraitMeta "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Meta_Query.php"
    click TraitTax "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Tax_Query.php"
    click TraitInclude "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Include_Posts.php"
    click TraitExcludeCurr "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Exclude_Current.php"
    click TraitExcludeTax "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Exclude_Taxonomies.php"
    click TraitMultiple "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Multiple_Posts.php"
    click TraitParent "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Post_Parent.php"
    click TraitDisablePag "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/Traits/Disable_Pagination.php"
    click SupportQueryLoop "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/query-loop.php"
    click SupportTax "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/taxonomy.php"
    click SupportUtil "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/includes/utilities.php"
    click VariationsEntry "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/variations/index.js"
    click ControlsSetup "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/variations/controls.js"
    click CPostInclude "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-include-controls.js"
    click CPostExclude "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-exclude-controls.js"
    click CTaxQuery "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/taxonomy-query-control.js"
    click CSingleTax "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/single-taxonomy-control.js"
    click CPostMetaQuery "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-meta-query-controls.js"
    click CPostMeta "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-meta-control.js"
    click CPostDate "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-date-query-controls.js"
    click CPostOrder "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-order-controls.js"
    click CPostOffset "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-offset-controls.js"
    click CPostCount "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/post-count-controls.js"
    click CMultiplePost "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/multiple-post-select.js"
    click CExcludeTax "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/exclude-taxonomies.js"
    click CPaginationToggle "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/pagination-toggle.js"
    click CChildItemsToggle "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/child-items-toggle.js"
    click CIcons "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/components/icons.js"
    click SlotMain "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/slots/aql-controls.js"
    click SlotInherited "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/slots/aql-controls-inherited-query.js"
    click SlotLegacy "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/slots/aql-legacy-controls.js"
    click HookDebounce "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/hooks/useDebouncedInputValue.js"
    click PolyfillPreGB "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/legacy-controls/pre-gb-19.js"
    click UtilJS "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/src/utils/index.js"
    click Webpack "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/webpack.config.js"
    click Npm "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/package.json"
    click Composer "https://github.com/ryanwelcher/advanced-query-loop/blob/trunk/composer.json"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef php fill:#bbf,stroke:#333,stroke-width:1px
    classDef trait fill:#ddf,stroke:#333,stroke-width:1px
    classDef js fill:#bfb,stroke:#333,stroke-width:1px
    classDef component fill:#afa,stroke:#333,stroke-width:1px
    classDef tool fill:#ffd,stroke:#333,stroke-width:1px
    classDef ci fill:#fdd,stroke:#333,stroke-width:1px
```
