# googleapis/google-cloud-php-retail architecture

> Architecture diagram of the GitHub repository googleapis/google-cloud-php-retail, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googleapis/google-cloud-php-retail
- Repository: https://github.com/googleapis/google-cloud-php-retail

## Overview

1. This repository is a generated PHP client library for Google Cloud Retail, not an application server. Its main purpose is to provide typed client classes and protobuf-style message objects for calling the Google Cloud Retail API from PHP.

2. The core architectural boundary is the network call to Google’s Retail backend. Everything in this repo is a client-side adapter layer: request/response models, service clients, transport configuration, and sample usage. It does not contain business logic or persistent storage of its own.

3. The API surface is organized by service under `src/V2/Client/`. Each client maps to a backend service: `CatalogServiceClient`, `ProductServiceClient`, `SearchServiceClient`, `CompletionServiceClient`, `ControlServiceClient`, `ServingConfigServiceClient`, `ModelServiceClient`, `PredictionServiceClient`, `UserEventServiceClient`, `AnalyticsServiceClient`, and `ConversationalSearchServiceClient`.

4. The data model lives primarily in `src/V2/`. These classes represent request/response messages and domain entities such as `Catalog`, `Product`, `ServingConfig`, `Control`, `UserEvent`, `SearchRequest`, `SearchResponse`, `PredictRequest`, and many nested message/value types. The nested directories under `src/V2/*` reflect structured submessages and enums.

5. Request/response flow is straightforward: caller code instantiates a client, builds a request object, sends it through the client, and receives a typed response object. The README sample shows this pattern for `CatalogServiceClient->getAttributesConfig()`, but the same pattern applies across the whole API.

6. The library supports two transport backends: gRPC and REST over HTTP/1.1. The per-service config files in `src/V2/resources/` provide the generated transport metadata and method descriptors needed to route each client call over the selected transport.

7. The repository includes generated service metadata in `metadata/V2/` and `src/V2/gapic_metadata.json`. These files define the service/method surface used by the generator and by the client runtime to map methods, endpoints, and pagination/operation behavior.

8. The operational flows reflected in the API are centered on retail search and recommendations:
   - catalog/product management and indexing,
   - user event ingestion and purge/rejoin,
   - search and completion serving,
   - serving config and control management,
   - model training/tuning/pause/resume,
   - predictions and analytics export,
   - conversational and generative search features.
   These are separate service boundaries rather than a single monolith.

9. Long-running or bulk workflows are represented by specialized request/response and metadata classes, such as import/export, purge, tune, and batch update operations. This suggests asynchronous backend processing, with the PHP client acting as a submission and polling/control layer rather than doing the work itself.

10. The `samples/V2/` tree demonstrates one-file, task-specific entry points for each API method. These are not part of the library runtime; they are usage examples showing how callers can invoke the clients for catalog updates, search, model operations, and event ingestion.

11. Tests are concentrated in `tests/Unit/V2/Client/`, one test file per service client. This reflects the architectural contract of the library: each client is validated independently against its expected generated behavior and request/response wiring.

12. Tooling and packaging are standard PHP/Composer. `composer.json` defines the package, `phpunit.xml.dist` drives unit tests, and `.github` plus contributor docs support release and maintenance workflows. `owlbot.py` indicates the repository is generator-managed, which is why the code layout is highly regular.

13. For an architecture diagram, the main boxes should be: PHP caller code → generated service client → transport layer (REST/gRPC) → Google Cloud Retail API backend. Supporting boxes around that path are the request/response model classes, service config/metadata, samples, and unit tests.

Main entry points: [`src/V2/resources`](https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2/resources) (Service resources), [`samples/V2`](https://github.com/googleapis/google-cloud-php-retail/tree/main/samples/V2) (Samples), [`src/V2/Client/CatalogServiceClient.php`](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/CatalogServiceClient.php) (Catalog client), [`src/V2/Client/ProductServiceClient.php`](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ProductServiceClient.php) (Product client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_php_caller(("PHP caller<br/>consumer"))
  node_catalog_client["Catalog client<br/>service client"]
  node_product_client["Product client<br/>service client"]
  node_search_client["Search client<br/>service client"]
  node_completion_client["Completion client<br/>service client"]
  node_control_client["Control client<br/>service client"]
  node_serving_client["Serving config client<br/>service client"]
  node_model_client["Model client<br/>service client"]
  node_prediction_client["Prediction client<br/>service client"]
  node_user_event_client["User event client<br/>service client"]
  node_analytics_client["Analytics client<br/>service client"]
  node_conversational_client["Conversational client<br/>service client"]
end

subgraph group_data_model["Data Model"]
  node_message_models[("V2 messages<br/>protobuf-style messages")]
  node_nested_types["Nested types<br/>submessages/enums"]
end

subgraph group_runtime["Runtime & Transport"]
  node_gapic_metadata["Gapic metadata<br/>surface metadata"]
  node_service_resources["Service resources<br/>transport config"]
  node_metadata_files["Metadata files<br/>generator metadata"]
  node_google_retail_api(("Retail backend<br/>cloud API"))
end

subgraph group_usage_quality["Usage & Quality"]
  node_samples["Samples<br/>usage examples"]
  node_unit_tests["Unit tests<br/>client tests"]
  node_composer_tooling{{"Composer tooling<br/>package/test config<br/>[composer.json]"}}
end

node_php_caller -->|"uses"| node_catalog_client
node_php_caller -->|"uses"| node_product_client
node_php_caller -->|"uses"| node_search_client
node_php_caller -->|"uses"| node_completion_client
node_php_caller -->|"uses"| node_control_client
node_php_caller -->|"uses"| node_serving_client
node_php_caller -->|"uses"| node_model_client
node_php_caller -->|"uses"| node_prediction_client
node_php_caller -->|"uses"| node_user_event_client
node_php_caller -->|"uses"| node_analytics_client
node_php_caller -->|"uses"| node_conversational_client
node_catalog_client -->|"serializes"| node_message_models
node_product_client -->|"serializes"| node_message_models
node_search_client -->|"serializes"| node_message_models
node_model_client -->|"serializes"| node_message_models
node_message_models -->|"contains"| node_nested_types
node_catalog_client -->|"routes via"| node_service_resources
node_product_client -->|"routes via"| node_service_resources
node_search_client -->|"routes via"| node_service_resources
node_completion_client -->|"routes via"| node_service_resources
node_control_client -->|"routes via"| node_service_resources
node_serving_client -->|"routes via"| node_service_resources
node_model_client -->|"routes via"| node_service_resources
node_prediction_client -->|"routes via"| node_service_resources
node_user_event_client -->|"routes via"| node_service_resources
node_analytics_client -->|"routes via"| node_service_resources
node_conversational_client -->|"routes via"| node_service_resources
node_service_resources -->|"connects to"| node_google_retail_api
node_gapic_metadata -.->|"describes"| node_service_resources
node_metadata_files -.->|"feeds"| node_gapic_metadata
node_samples -.->|"illustrates"| node_php_caller
node_samples -.->|"illustrates"| node_catalog_client
node_samples -.->|"illustrates"| node_product_client
node_samples -.->|"illustrates"| node_search_client
node_samples -.->|"illustrates"| node_model_client
node_unit_tests -.->|"validates"| node_catalog_client
node_unit_tests -.->|"validates"| node_product_client
node_unit_tests -.->|"validates"| node_search_client
node_composer_tooling -.->|"runs"| node_unit_tests

click node_catalog_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/CatalogServiceClient.php"
click node_product_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ProductServiceClient.php"
click node_search_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/SearchServiceClient.php"
click node_completion_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/CompletionServiceClient.php"
click node_control_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ControlServiceClient.php"
click node_serving_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ServingConfigServiceClient.php"
click node_model_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ModelServiceClient.php"
click node_prediction_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/PredictionServiceClient.php"
click node_user_event_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/UserEventServiceClient.php"
click node_analytics_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/AnalyticsServiceClient.php"
click node_conversational_client "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ConversationalSearchServiceClient.php"
click node_message_models "https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2"
click node_nested_types "https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2/SearchRequest"
click node_gapic_metadata "https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/gapic_metadata.json"
click node_service_resources "https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2/resources"
click node_metadata_files "https://github.com/googleapis/google-cloud-php-retail/tree/main/metadata/V2"
click node_samples "https://github.com/googleapis/google-cloud-php-retail/tree/main/samples/V2"
click node_unit_tests "https://github.com/googleapis/google-cloud-php-retail/tree/main/tests/Unit/V2/Client"
click node_composer_tooling "https://github.com/googleapis/google-cloud-php-retail/blob/main/composer.json"

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_php_caller,node_catalog_client,node_product_client,node_search_client,node_completion_client,node_control_client,node_serving_client,node_model_client,node_prediction_client,node_user_event_client,node_analytics_client,node_conversational_client toneBlue
class node_message_models,node_nested_types toneAmber
class node_gapic_metadata,node_service_resources,node_metadata_files,node_google_retail_api toneMint
class node_samples,node_unit_tests,node_composer_tooling toneRose
```

## Components

### Public API

Generated service clients exposed to PHP callers

- **PHP caller**: consumer · External PHP code using the library
- [Catalog client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/CatalogServiceClient.php): service client · Catalog and attributes API · `src/V2/Client/CatalogServiceClient.php`
- [Product client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ProductServiceClient.php): service client · Product and inventory API · `src/V2/Client/ProductServiceClient.php`
- [Search client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/SearchServiceClient.php): service client · Search serving API · `src/V2/Client/SearchServiceClient.php`
- [Completion client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/CompletionServiceClient.php): service client · Autocomplete and completion API · `src/V2/Client/CompletionServiceClient.php`
- [Control client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ControlServiceClient.php): service client · Control rule management API · `src/V2/Client/ControlServiceClient.php`
- [Serving config client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ServingConfigServiceClient.php): service client · Serving configuration API · `src/V2/Client/ServingConfigServiceClient.php`
- [Model client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ModelServiceClient.php): service client · Model lifecycle and tuning API · `src/V2/Client/ModelServiceClient.php`
- [Prediction client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/PredictionServiceClient.php): service client · Prediction API · `src/V2/Client/PredictionServiceClient.php`
- [User event client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/UserEventServiceClient.php): service client · User event ingestion and purge API · `src/V2/Client/UserEventServiceClient.php`
- [Analytics client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/AnalyticsServiceClient.php): service client · Analytics export API · `src/V2/Client/AnalyticsServiceClient.php`
- [Conversational client](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/Client/ConversationalSearchServiceClient.php): service client · Conversational search API · `src/V2/Client/ConversationalSearchServiceClient.php`

### Data Model

Typed request, response, and resource messages

- [V2 messages](https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2): protobuf-style messages · Request, response, and domain message classes · `src/V2`
- [Nested types](https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2/SearchRequest): submessages/enums · Structured submessages, enums, and option blocks · `src/V2/SearchRequest`

### Runtime & Transport

Service metadata and transport routing configuration

- [Gapic metadata](https://github.com/googleapis/google-cloud-php-retail/blob/main/src/V2/gapic_metadata.json): surface metadata · Generated service and method surface description · `src/V2/gapic_metadata.json`
- [Service resources](https://github.com/googleapis/google-cloud-php-retail/tree/main/src/V2/resources): transport config · Per-service REST and descriptor configuration · `src/V2/resources`
- [Metadata files](https://github.com/googleapis/google-cloud-php-retail/tree/main/metadata/V2): generator metadata · Generated backend and method metadata under metadata/V2 · `metadata/V2`
- **Retail backend**: cloud API · Google Cloud Retail service endpoints

### Usage & Quality

Samples, tests, and package tooling

- [Samples](https://github.com/googleapis/google-cloud-php-retail/tree/main/samples/V2): usage examples · Method-by-method client call examples · `samples/V2`
- [Unit tests](https://github.com/googleapis/google-cloud-php-retail/tree/main/tests/Unit/V2/Client): client tests · Per-client generated behavior tests · `tests/Unit/V2/Client`
- [Composer tooling](https://github.com/googleapis/google-cloud-php-retail/blob/main/composer.json): package/test config · Packaging and PHPUnit configuration · `composer.json`

## Connections

- PHP caller → Catalog client: uses · Caller creates a service client and invokes methods
- PHP caller → Product client: uses · Caller creates a service client and invokes methods
- PHP caller → Search client: uses · Caller creates a service client and invokes methods
- PHP caller → Completion client: uses · Caller creates a service client and invokes methods
- PHP caller → Control client: uses · Caller creates a service client and invokes methods
- PHP caller → Serving config client: uses · Caller creates a service client and invokes methods
- PHP caller → Model client: uses · Caller creates a service client and invokes methods
- PHP caller → Prediction client: uses · Caller creates a service client and invokes methods
- PHP caller → User event client: uses · Caller creates a service client and invokes methods
- PHP caller → Analytics client: uses · Caller creates a service client and invokes methods
- PHP caller → Conversational client: uses · Caller creates a service client and invokes methods
- Catalog client → V2 messages: serializes · Builds requests and returns typed responses
- Product client → V2 messages: serializes · Builds requests and returns typed responses
- Search client → V2 messages: serializes · Builds requests and returns typed responses
- Model client → V2 messages: serializes · Builds requests and returns typed responses
- V2 messages → Nested types: contains · Models include nested message and enum types
- Catalog client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Product client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Search client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Completion client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Control client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Serving config client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Model client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Prediction client → Service resources: routes via · Client methods use transport-specific config and descriptors
- User event client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Analytics client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Conversational client → Service resources: routes via · Client methods use transport-specific config and descriptors
- Service resources → Retail backend: connects to · REST or gRPC transport reaches the Retail backend
- Gapic metadata → Service resources: describes · Method and endpoint metadata feed transport config
- Metadata files → Gapic metadata: feeds · Generator metadata contributes to runtime surface generation
- Samples → PHP caller: illustrates · Sample entry points show how callers use the library
- Samples → Catalog client: illustrates · Samples demonstrate specific service methods
- Samples → Product client: illustrates · Samples demonstrate specific service methods
- Samples → Search client: illustrates · Samples demonstrate specific service methods
- Samples → Model client: illustrates · Samples demonstrate specific service methods
- Unit tests → Catalog client: validates · Per-service tests verify generated client behavior
- Unit tests → Product client: validates · Per-service tests verify generated client behavior
- Unit tests → Search client: validates · Per-service tests verify generated client behavior
- Composer tooling → Unit tests: runs · Composer and PHPUnit configuration drive unit testing