# virtocommerce/vc-module-x-catalog architecture

> Architecture diagram of the GitHub repository virtocommerce/vc-module-x-catalog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virtocommerce/vc-module-x-catalog
- Repository: https://github.com/virtocommerce/vc-module-x-catalog

## Overview

xCatalog is Virto Commerce’s GraphQL catalog experience module, providing search-index-backed catalog queries. The main storefront flow maps GraphQL product-search arguments into a query, builds and executes an index request, then enriches the response through a product evaluation pipeline. Separate query families cover categories, brands, properties, suggestions, promotions, associations, videos, and fulfillment centers. The tree and excerpts establish the product/search path and selected category and brand behavior; other listed capabilities are represented without asserting unshown call wiring.

Main entry points: [`src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs) (Category search handler), [`src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs) (Product search handler), [`src/VirtoCommerce.XCatalog.Core/Queries/SearchProductQuery.cs`](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/SearchProductQuery.cs) (Product query), [`src/VirtoCommerce.XCatalog.Data/Index/IndexSearchRequestBuilder.cs`](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Index/IndexSearchRequestBuilder.cs) (Index request builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["GraphQL API"]
  node_schema["Catalog schemas<br/>[Schemas]"]
  node_product_query["Product query"]
  node_category_query["Category query"]
  node_base_query["Catalog query base"]
end

subgraph group_query["Query Handling"]
  node_product_handler["Product search handler"]
  node_category_handler["Category search handler"]
end

subgraph group_search["Index Search"]
  node_request_builder["Index request builder"]
  node_field_mapper["Index field mapping"]
  node_search_index[("Search index")]
  node_mapper["Catalog mapper<br/>[XCatalogMapper.cs]"]
end

subgraph group_enrich["Response Enrichment"]
  node_product_pipeline["Product enrichment<br/>[Middlewares]"]
  node_category_pipeline["Category enrichment"]
end

subgraph group_catalog["Catalog Capabilities"]
  node_category_children["Child categories"]
  node_brand_search["Brand search"]
  node_other_queries["Catalog query handlers<br/>[Queries]"]
  node_product_models["Expanded products<br/>[ExpProduct.cs]"]
  node_response_models["Query response models<br/>[Models]"]
end

node_client(("Storefront client"))

node_client -.->|"queries"| node_schema
node_schema -.->|"exposes"| node_product_query
node_product_handler -->|"handles"| node_product_query
node_category_handler -->|"handles"| node_category_query
node_product_handler -->|"builds request"| node_request_builder
node_category_handler -->|"builds request"| node_request_builder
node_request_builder -.->|"searches"| node_search_index
node_product_handler -->|"searches products"| node_search_index
node_category_handler -->|"searches categories"| node_search_index
node_product_handler -->|"maps results"| node_mapper
node_category_handler -->|"maps results"| node_mapper
node_product_handler -->|"evaluates response"| node_product_pipeline
node_product_pipeline -.->|"enriches"| node_product_models
node_category_handler -.->|"loads categories"| node_category_pipeline
node_category_handler -->|"requests children"| node_category_children
node_category_children -->|"filters by products"| node_product_query
node_brand_search -->|"queries brand facets"| node_product_query
node_product_handler -->|"returns results"| node_response_models
node_category_handler -->|"returns results"| node_response_models
node_other_queries -.->|"serves catalog searches"| node_search_index

click node_schema "https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Core/Schemas"
click node_product_query "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/SearchProductQuery.cs"
click node_category_query "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/SearchCategoryQuery.cs"
click node_base_query "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/CatalogQueryBase.cs"
click node_product_handler "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs"
click node_category_handler "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs"
click node_category_children "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/ChildCategoriesQueryHandler.cs"
click node_brand_search "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchBrandQueryHandler.cs"
click node_other_queries "https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Data/Queries"
click node_request_builder "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Index/IndexSearchRequestBuilder.cs"
click node_field_mapper "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Index/IndexFieldsMapper.cs"
click node_mapper "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Services/XCatalogMapper.cs"
click node_product_pipeline "https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Data/Middlewares"
click node_category_pipeline "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Middlewares/EnsureCategoryLoadedMiddleware.cs"
click node_product_models "https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Models/ExpProduct.cs"
click node_response_models "https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Core/Models"

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_schema,node_product_query,node_category_query,node_base_query,node_client toneBlue
class node_product_handler,node_category_handler toneAmber
class node_request_builder,node_field_mapper,node_search_index,node_mapper toneMint
class node_product_pipeline,node_category_pipeline toneRose
class node_category_children,node_brand_search,node_other_queries,node_product_models,node_response_models toneIndigo
```

## Components

### GraphQL API

- [Catalog schemas](https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Core/Schemas): `src/VirtoCommerce.XCatalog.Core/Schemas`
- [Product query](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/SearchProductQuery.cs): `src/VirtoCommerce.XCatalog.Core/Queries/SearchProductQuery.cs`
- [Category query](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/SearchCategoryQuery.cs): `src/VirtoCommerce.XCatalog.Core/Queries/SearchCategoryQuery.cs`
- [Catalog query base](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Queries/CatalogQueryBase.cs): `src/VirtoCommerce.XCatalog.Core/Queries/CatalogQueryBase.cs`

### Query Handling

- [Product search handler](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs): `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`
- [Category search handler](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs): `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`

### Index Search

- [Index request builder](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Index/IndexSearchRequestBuilder.cs): `src/VirtoCommerce.XCatalog.Data/Index/IndexSearchRequestBuilder.cs`
- [Index field mapping](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Index/IndexFieldsMapper.cs): `src/VirtoCommerce.XCatalog.Data/Index/IndexFieldsMapper.cs`
- **Search index**
- [Catalog mapper](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Services/XCatalogMapper.cs): `src/VirtoCommerce.XCatalog.Data/Services/XCatalogMapper.cs`

### Response Enrichment

- [Product enrichment](https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Data/Middlewares): `src/VirtoCommerce.XCatalog.Data/Middlewares`
- [Category enrichment](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Middlewares/EnsureCategoryLoadedMiddleware.cs): `src/VirtoCommerce.XCatalog.Data/Middlewares/EnsureCategoryLoadedMiddleware.cs`

### Catalog Capabilities

- [Child categories](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/ChildCategoriesQueryHandler.cs): `src/VirtoCommerce.XCatalog.Data/Queries/ChildCategoriesQueryHandler.cs`
- [Brand search](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Data/Queries/SearchBrandQueryHandler.cs): `src/VirtoCommerce.XCatalog.Data/Queries/SearchBrandQueryHandler.cs`
- [Catalog query handlers](https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Data/Queries): `src/VirtoCommerce.XCatalog.Data/Queries`
- [Expanded products](https://github.com/virtocommerce/vc-module-x-catalog/blob/dev/src/VirtoCommerce.XCatalog.Core/Models/ExpProduct.cs): `src/VirtoCommerce.XCatalog.Core/Models/ExpProduct.cs`
- [Query response models](https://github.com/virtocommerce/vc-module-x-catalog/tree/dev/src/VirtoCommerce.XCatalog.Core/Models): `src/VirtoCommerce.XCatalog.Core/Models`

### Other components

- **Storefront client**

## Connections

- Storefront client → Catalog schemas: queries (evidence: `README.md`)
- Catalog schemas → Product query: exposes
- Product search handler → Product query: handles (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Category search handler → Category query: handles (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Product search handler → Index request builder: builds request (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Category search handler → Index request builder: builds request (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Index request builder → Search index: searches
- Product search handler → Search index: searches products (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Category search handler → Search index: searches categories (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Product search handler → Catalog mapper: maps results (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Category search handler → Catalog mapper: maps results (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Product search handler → Product enrichment: evaluates response (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Product enrichment → Expanded products: enriches (evidence: `src/VirtoCommerce.XCatalog.Data/Middlewares/ResolveSearchFiltersResponseMiddleware.cs`)
- Category search handler → Category enrichment: loads categories
- Category search handler → Child categories: requests children (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Child categories → Product query: filters by products (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/ChildCategoriesQueryHandler.cs`)
- Brand search → Product query: queries brand facets (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchBrandQueryHandler.cs`)
- Product search handler → Query response models: returns results (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchProductQueryHandler.cs`)
- Category search handler → Query response models: returns results (evidence: `src/VirtoCommerce.XCatalog.Data/Queries/SearchCategoryQueryHandler.cs`)
- Catalog query handlers → Search index: serves catalog searches