# power-vending/laravel-api-query-builder architecture

> Architecture diagram of the GitHub repository power-vending/laravel-api-query-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/power-vending/laravel-api-query-builder
- Repository: https://github.com/power-vending/laravel-api-query-builder

## Overview

Laravel JSON Query Builder turns request parameters into Eloquent query constraints and paginated results, and also exposes a schema endpoint describing searchable columns, operators, and relations. The main query path is documented and partly visible in source; individual non-search parameter implementations are represented at their shared directory because their internals were not sampled. The schema generator excerpt is partial, so only its shown schema and database-metadata responsibilities are mapped.

Main entry points: [`src/Http/Controllers/SchemaController.php`](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Http/Controllers/SchemaController.php) (Schema endpoint), [`src/RequestParameters/SearchParameter.php`](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/RequestParameters/SearchParameter.php) (Search parameter), [`src/Schema/QueryBuilderSchema.php`](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Schema/QueryBuilderSchema.php) (Schema generator), [`src/ApiQuery.php`](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/ApiQuery.php) (Request query dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query execution"]
  node_trait["Model query scopes"]
  node_apiquery["Request query dispatcher<br/>[ApiQuery.php]"]
  node_params["Request parameter handlers"]
end

subgraph group_search["Search parsing"]
  node_searchparam["Search parameter"]
  node_parser["Search parsers<br/>[SearchParser.php]"]
  node_customparser["Custom field parser"]
  node_callbacks["Operator callbacks"]
  node_types["Search value types"]
end

subgraph group_schema["Schema discovery"]
  node_schemarequest["Schema request validation<br/>[SchemaRequest.php]"]
  node_schemacontroller["Schema endpoint"]
  node_schema["Schema generator"]
  node_relationnormalizer["Relation name normalization"]
  node_serviceprovider["Laravel route registration"]
  node_routes["Package schema route<br/>[api.php]"]
end

subgraph group_config["Configuration"]
  node_operatorsconfig["Operator registry"]
  node_requestconfig["Parameter registry"]
  node_configfile["Package configuration"]
  node_modelconfig["Model restrictions<br/>[ModelConfig.php]"]
end

node_client(("API client"))
node_eloquent["Eloquent builder"]
node_database[("Application database")]

node_client -->|"supplies query"| node_trait
node_trait -->|"dispatches input"| node_apiquery
node_trait -->|"paginates"| node_eloquent
node_apiquery -->|"loads handlers"| node_requestconfig
node_requestconfig -->|"reads registration"| node_configfile
node_apiquery -->|"runs handlers"| node_params
node_searchparam -->|"recurses nested search"| node_apiquery
node_searchparam -->|"loads operators"| node_operatorsconfig
node_operatorsconfig -->|"reads registration"| node_configfile
node_searchparam -->|"parses criteria"| node_parser
node_searchparam -->|"parses custom fields"| node_customparser
node_searchparam -->|"dispatches operator"| node_callbacks
node_callbacks -->|"adds constraints"| node_eloquent
node_parser -->|"checks model rules"| node_modelconfig
node_client -->|"requests schema"| node_schemacontroller
node_schemacontroller -->|"validates request"| node_schemarequest
node_serviceprovider -->|"registers routes"| node_routes
node_serviceprovider -->|"registers action"| node_schemacontroller
node_schemacontroller -->|"generates schema"| node_schema
node_schemacontroller -->|"checks relation rules"| node_modelconfig
node_schemacontroller -->|"normalizes relations"| node_relationnormalizer
node_schema -->|"applies restrictions"| node_modelconfig
node_schema -->|"lists operators"| node_operatorsconfig
node_schema -->|"reads column metadata"| node_database
node_schema -->|"classifies columns"| node_types
node_eloquent -->|"executes query"| node_database

click node_trait "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Traits/ApiQueryBuilder.php"
click node_apiquery "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/ApiQuery.php"
click node_params "https://github.com/power-vending/laravel-api-query-builder/tree/master/src/RequestParameters"
click node_searchparam "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/RequestParameters/SearchParameter.php"
click node_parser "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/SearchParser.php"
click node_customparser "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/CustomFieldSearchParser.php"
click node_callbacks "https://github.com/power-vending/laravel-api-query-builder/tree/master/src/SearchCallbacks"
click node_operatorsconfig "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/OperatorsConfig.php"
click node_requestconfig "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/RequestParametersConfig.php"
click node_configfile "https://github.com/power-vending/laravel-api-query-builder/blob/master/config/api-query-builder.php"
click node_schemarequest "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Http/Requests/SchemaRequest.php"
click node_schemacontroller "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Http/Controllers/SchemaController.php"
click node_schema "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Schema/QueryBuilderSchema.php"
click node_modelconfig "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/ModelConfig.php"
click node_relationnormalizer "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Support/RelationMethodNormalizer.php"
click node_serviceprovider "https://github.com/power-vending/laravel-api-query-builder/blob/master/src/ApiQueryServiceProvider.php"
click node_routes "https://github.com/power-vending/laravel-api-query-builder/blob/master/routes/api.php"
click node_types "https://github.com/power-vending/laravel-api-query-builder/tree/master/src/Types"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_trait,node_apiquery,node_params,node_client toneBlue
class node_searchparam,node_parser,node_customparser,node_callbacks,node_types,node_database toneAmber
class node_schemarequest,node_schemacontroller,node_schema,node_relationnormalizer,node_serviceprovider,node_routes toneMint
class node_operatorsconfig,node_requestconfig,node_configfile,node_modelconfig toneRose
class node_eloquent toneIndigo
```

## Components

### Query execution

- [Model query scopes](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Traits/ApiQueryBuilder.php): `src/Traits/ApiQueryBuilder.php`
- [Request query dispatcher](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/ApiQuery.php): `src/ApiQuery.php`
- [Request parameter handlers](https://github.com/power-vending/laravel-api-query-builder/tree/master/src/RequestParameters): `src/RequestParameters`

### Search parsing

- [Search parameter](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/RequestParameters/SearchParameter.php): `src/RequestParameters/SearchParameter.php`
- [Search parsers](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/SearchParser.php): `src/SearchParser.php`
- [Custom field parser](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/CustomFieldSearchParser.php): `src/CustomFieldSearchParser.php`
- [Operator callbacks](https://github.com/power-vending/laravel-api-query-builder/tree/master/src/SearchCallbacks): `src/SearchCallbacks`
- [Search value types](https://github.com/power-vending/laravel-api-query-builder/tree/master/src/Types): `src/Types`

### Schema discovery

- [Schema request validation](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Http/Requests/SchemaRequest.php): `src/Http/Requests/SchemaRequest.php`
- [Schema endpoint](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Http/Controllers/SchemaController.php): `src/Http/Controllers/SchemaController.php`
- [Schema generator](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Schema/QueryBuilderSchema.php): `src/Schema/QueryBuilderSchema.php`
- [Relation name normalization](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Support/RelationMethodNormalizer.php): `src/Support/RelationMethodNormalizer.php`
- [Laravel route registration](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/ApiQueryServiceProvider.php): `src/ApiQueryServiceProvider.php`
- [Package schema route](https://github.com/power-vending/laravel-api-query-builder/blob/master/routes/api.php): `routes/api.php`

### Configuration

- [Operator registry](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/OperatorsConfig.php): `src/Config/OperatorsConfig.php`
- [Parameter registry](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/RequestParametersConfig.php): `src/Config/RequestParametersConfig.php`
- [Package configuration](https://github.com/power-vending/laravel-api-query-builder/blob/master/config/api-query-builder.php): `config/api-query-builder.php`
- [Model restrictions](https://github.com/power-vending/laravel-api-query-builder/blob/master/src/Config/ModelConfig.php): `src/Config/ModelConfig.php`

### Other components

- **API client**
- **Eloquent builder**
- **Application database**

## Connections

- API client → Model query scopes: supplies query
- Model query scopes → Request query dispatcher: dispatches input
- Model query scopes → Eloquent builder: paginates
- Request query dispatcher → Parameter registry: loads handlers
- Parameter registry → Package configuration: reads registration
- Request query dispatcher → Request parameter handlers: runs handlers
- Search parameter → Request query dispatcher: recurses nested search
- Search parameter → Operator registry: loads operators
- Operator registry → Package configuration: reads registration
- Search parameter → Search parsers: parses criteria
- Search parameter → Custom field parser: parses custom fields
- Search parameter → Operator callbacks: dispatches operator
- Operator callbacks → Eloquent builder: adds constraints
- Search parsers → Model restrictions: checks model rules
- API client → Schema endpoint: requests schema
- Schema endpoint → Schema request validation: validates request
- Laravel route registration → Package schema route: registers routes
- Laravel route registration → Schema endpoint: registers action
- Schema endpoint → Schema generator: generates schema
- Schema endpoint → Model restrictions: checks relation rules
- Schema endpoint → Relation name normalization: normalizes relations
- Schema generator → Model restrictions: applies restrictions
- Schema generator → Operator registry: lists operators
- Schema generator → Application database: reads column metadata
- Schema generator → Search value types: classifies columns
- Eloquent builder → Application database: executes query