# vtex-apps/search-resolver architecture

> Architecture diagram of the GitHub repository vtex-apps/search-resolver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vtex-apps/search-resolver
- Repository: https://github.com/vtex-apps/search-resolver

## Overview

1. **What this repo is**
   This is a VTEX IO GraphQL resolver app that implements the VTEX search protocol described by `search-graphql`. Its job is not to serve a UI, but to expose GraphQL fields that translate search-related requests into VTEX backend API calls.

2. **Primary runtime boundary**
   The main execution path starts in `node/index.ts` and is organized around GraphQL resolvers. The code is TypeScript-based, runs in the Node runtime, and is packaged as a VTEX app via `manifest.json`, `node/service.json`, and the `.vtex` deployment metadata.

3. **API layer: resolvers**
   The `node/resolvers` folder is the GraphQL-facing boundary. It is split by domain:
   - `resolvers/search`: product, SKU, category, brand, autocomplete, recommendation, breadcrumbs, pricing, metadata, URLs, and related search entities.
   - `resolvers/stats`: search analytics/count-style endpoints.
   - `resolvers/benefits`: benefit-related search data.
   These resolvers shape the GraphQL response and delegate almost all data access to services.

4. **Service layer: business orchestration**
   The `node/services` folder contains the main orchestration logic. This layer aggregates and normalizes data before it reaches resolvers. Key service areas are:
   - `product`, `productSearch`, `facets`, `autocomplete`
   - `banners`, `settings`, `pdpConfig`
   This is where request-level composition happens, including combining search results, facet metadata, and product-related enrichment.

5. **Client layer: external VTEX API access**
   The `node/clients` folder isolates calls to external VTEX services:
   - `search.ts` for catalog/search API access
   - `checkout.ts` for checkout/product pricing-related data
   - `rewriter.ts` for URL/query rewriting behavior
   - `intelligent-search-api.ts` and `clients/intsch` for Intelligent Search integrations
   This boundary matters because most repository logic is about adapting these APIs into the search-graphql schema.

6. **Intelligent Search integration**
   The `node/clients/intsch` submodule is a specialized adapter with its own types and utilities. It indicates the app supports VTEX Intelligent Search as a separate backend path, likely used by autocomplete, search queries, or metadata enrichment when configured.

7. **GraphQL field modifiers**
   `node/directives` contains custom GraphQL directives such as `withSegment` and `toVtexAssets`. These are cross-cutting schema behaviors that alter resolution based on context or transform asset URLs/paths, rather than being part of the core search logic.

8. **Shared utilities and domain transformations**
   `node/utils` holds reusable domain logic: category tree traversal, search state parsing, slug/string helpers, cookie handling, comparisons, fallback behavior, and VTEX-specific helpers like `vbase`. These utilities are used across services and resolvers to keep protocol translation consistent.

9. **Compatibility and feature control**
   `node/commons/compatibility-layer.ts` and `node/featureFlags.ts` indicate the app supports legacy behavior and conditional paths. In an architecture diagram, these should be shown as a cross-cutting layer between resolvers/services and the lower-level clients, because they influence how requests are interpreted or which backend behavior is selected.

10. **Data flow to draw**
   The most important flow is:
   GraphQL request → resolver → service orchestration → VTEX client(s) → external VTEX APIs → normalized response back through resolver.
   Some flows also incorporate directives, feature flags, and compatibility adjustments before the service/client call, plus tests and mocks around each layer to validate those transformations.

11. **Testing and contract protection**
   The repository includes many colocated tests under `node/resolvers`, `node/services`, and `node/utils`, plus mocks under `node/__mocks__` and `node/mocks`. This suggests the architecture is heavily contract-driven: tests validate the mapping from VTEX backend shapes to the GraphQL search schema.

12. **Operational shape**
   The app is designed to be deployed as a VTEX service, not as a standalone server. The key operational dependencies are the VTEX catalog/search/checkout endpoints and, optionally, Intelligent Search. The repo’s structure makes the separation between schema, orchestration, external API adapters, and shared search-domain utilities very explicit.

Main entry points: [`node/resolvers/search/index.ts`](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/search/index.ts) (Search resolvers), [`node/services/productSearch.ts`](https://github.com/vtex-apps/search-resolver/blob/main/node/services/productSearch.ts) (Search service), [`node/services/product.ts`](https://github.com/vtex-apps/search-resolver/blob/main/node/services/product.ts) (Product service), [`node/resolvers/index.ts`](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/index.ts) (Resolvers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["App entry<br/>vt-ex app<br/>[index.ts]"]
end

subgraph group_api["GraphQL API"]
  node_graphql_resolvers["Resolvers<br/>graphql layer<br/>[index.ts]"]
  node_search_resolvers["Search resolvers<br/>graphql domain<br/>[index.ts]"]
  node_stats_resolvers["Stats resolvers<br/>graphql domain<br/>[index.ts]"]
  node_benefits_resolvers["Benefits resolvers<br/>graphql domain<br/>[index.ts]"]
  node_directives{{"Directives<br/>[index.ts]"}}
end

subgraph group_orchestration["Services"]
  node_product_service["Product service<br/>orchestration<br/>[product.ts]"]
  node_search_service["Search service<br/>orchestration<br/>[productSearch.ts]"]
  node_facets_service["Facets service<br/>orchestration<br/>[facets.ts]"]
  node_autocomplete_service["Autocomplete<br/>orchestration<br/>[autocomplete.ts]"]
  node_settings_service["Settings<br/>orchestration<br/>[settings.ts]"]
  node_pdp_config["PDP config<br/>orchestration<br/>[pdpConfig.ts]"]
end

subgraph group_integrations["Clients"]
  node_search_client[("Search API<br/>vtex client<br/>[search.ts]")]
  node_checkout_client[("Checkout API<br/>vtex client<br/>[checkout.ts]")]
  node_rewriter_client[("Rewriter<br/>vtex client<br/>[rewriter.ts]")]
  node_intsch_client[("Intelligent Search<br/>integration")]
end

subgraph group_shared["Shared"]
  node_compat_layer["Compatibility<br/>legacy layer"]
  node_feature_flags["Feature flags<br/>runtime flags<br/>[featureFlags.ts]"]
  node_utils["Utilities<br/>domain helpers<br/>[index.ts]"]
end

subgraph group_ops["Ops"]
  node_mocks_tests["Mocks & tests<br/>test support<br/>[contextFactory.ts]"]
  node_deployment["Deployment<br/>vtex packaging<br/>[manifest.json]"]
end

node_entry -->|"wires"| node_graphql_resolvers
node_graphql_resolvers -->|"routes"| node_search_resolvers
node_graphql_resolvers -->|"routes"| node_stats_resolvers
node_graphql_resolvers -->|"routes"| node_benefits_resolvers
node_search_resolvers -->|"delegates"| node_product_service
node_search_resolvers -->|"delegates"| node_search_service
node_search_resolvers -->|"delegates"| node_facets_service
node_search_resolvers -->|"delegates"| node_autocomplete_service
node_search_resolvers -->|"reads"| node_settings_service
node_search_resolvers -->|"reads"| node_pdp_config
node_stats_resolvers -->|"reads"| node_search_service
node_benefits_resolvers -->|"delegates"| node_product_service
node_product_service -->|"calls"| node_search_client
node_product_service -->|"calls"| node_checkout_client
node_search_service -->|"calls"| node_search_client
node_search_service -->|"calls"| node_rewriter_client
node_search_service -->|"optionally uses"| node_intsch_client
node_facets_service -->|"calls"| node_search_client
node_autocomplete_service -->|"optionally uses"| node_intsch_client
node_search_resolvers -->|"uses"| node_directives
node_stats_resolvers -->|"uses"| node_directives
node_product_service -->|"adapts"| node_compat_layer
node_search_service -->|"adapts"| node_compat_layer
node_search_service -->|"checks"| node_feature_flags
node_product_service -->|"uses"| node_utils
node_search_service -->|"uses"| node_utils
node_facets_service -->|"uses"| node_utils
node_directives -->|"uses"| node_utils
node_mocks_tests -.->|"covers"| node_search_resolvers
node_mocks_tests -.->|"covers"| node_product_service
node_mocks_tests -.->|"covers"| node_utils
node_deployment -->|"packages"| node_entry
node_deployment -->|"exposes"| node_graphql_resolvers

click node_entry "https://github.com/vtex-apps/search-resolver/blob/main/node/index.ts"
click node_graphql_resolvers "https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/index.ts"
click node_search_resolvers "https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/search/index.ts"
click node_stats_resolvers "https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/stats/index.ts"
click node_benefits_resolvers "https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/benefits/index.ts"
click node_directives "https://github.com/vtex-apps/search-resolver/blob/main/node/directives/index.ts"
click node_product_service "https://github.com/vtex-apps/search-resolver/blob/main/node/services/product.ts"
click node_search_service "https://github.com/vtex-apps/search-resolver/blob/main/node/services/productSearch.ts"
click node_facets_service "https://github.com/vtex-apps/search-resolver/blob/main/node/services/facets.ts"
click node_autocomplete_service "https://github.com/vtex-apps/search-resolver/blob/main/node/services/autocomplete.ts"
click node_settings_service "https://github.com/vtex-apps/search-resolver/blob/main/node/services/settings.ts"
click node_pdp_config "https://github.com/vtex-apps/search-resolver/blob/main/node/services/pdpConfig.ts"
click node_search_client "https://github.com/vtex-apps/search-resolver/blob/main/node/clients/search.ts"
click node_checkout_client "https://github.com/vtex-apps/search-resolver/blob/main/node/clients/checkout.ts"
click node_rewriter_client "https://github.com/vtex-apps/search-resolver/blob/main/node/clients/rewriter.ts"
click node_intsch_client "https://github.com/vtex-apps/search-resolver/blob/main/node/clients/intelligent-search-api.ts"
click node_compat_layer "https://github.com/vtex-apps/search-resolver/blob/main/node/commons/compatibility-layer.ts"
click node_feature_flags "https://github.com/vtex-apps/search-resolver/blob/main/node/featureFlags.ts"
click node_utils "https://github.com/vtex-apps/search-resolver/blob/main/node/utils/index.ts"
click node_mocks_tests "https://github.com/vtex-apps/search-resolver/blob/main/node/mocks/contextFactory.ts"
click node_deployment "https://github.com/vtex-apps/search-resolver/blob/main/manifest.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_entry toneBlue
class node_graphql_resolvers,node_search_resolvers,node_stats_resolvers,node_benefits_resolvers,node_directives toneAmber
class node_product_service,node_search_service,node_facets_service,node_autocomplete_service,node_settings_service,node_pdp_config toneMint
class node_search_client,node_checkout_client,node_rewriter_client,node_intsch_client toneRose
class node_compat_layer,node_feature_flags,node_utils toneIndigo
class node_mocks_tests,node_deployment toneTeal
```

## Components

### Runtime

Node/VTEX app entrypoint and deployment boundary

- [App entry](https://github.com/vtex-apps/search-resolver/blob/main/node/index.ts): vt-ex app · Bootstraps the Node runtime and wires the GraphQL service · `node/index.ts`

### GraphQL API

Resolvers and directives exposed to GraphQL

- [Resolvers](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/index.ts): graphql layer · GraphQL boundary for search, stats, and benefits · `node/resolvers/index.ts`
- [Search resolvers](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/search/index.ts): graphql domain · Search-facing query and field resolvers · `node/resolvers/search/index.ts`
- [Stats resolvers](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/stats/index.ts): graphql domain · Search count and analytics resolvers · `node/resolvers/stats/index.ts`
- [Benefits resolvers](https://github.com/vtex-apps/search-resolver/blob/main/node/resolvers/benefits/index.ts): graphql domain · Benefit-related search resolvers · `node/resolvers/benefits/index.ts`
- [Directives](https://github.com/vtex-apps/search-resolver/blob/main/node/directives/index.ts): graphql directives · Cross-cutting GraphQL behaviors and transforms · `node/directives/index.ts`

### Services

Request orchestration and domain composition

- [Product service](https://github.com/vtex-apps/search-resolver/blob/main/node/services/product.ts): orchestration · Product and SKU composition logic · `node/services/product.ts`
- [Search service](https://github.com/vtex-apps/search-resolver/blob/main/node/services/productSearch.ts): orchestration · Search result normalization and request shaping · `node/services/productSearch.ts`
- [Facets service](https://github.com/vtex-apps/search-resolver/blob/main/node/services/facets.ts): orchestration · Facet aggregation and search metadata assembly · `node/services/facets.ts`
- [Autocomplete](https://github.com/vtex-apps/search-resolver/blob/main/node/services/autocomplete.ts): orchestration · Autocomplete orchestration and suggestion shaping · `node/services/autocomplete.ts`
- [Settings](https://github.com/vtex-apps/search-resolver/blob/main/node/services/settings.ts): orchestration · App and search configuration access · `node/services/settings.ts`
- [PDP config](https://github.com/vtex-apps/search-resolver/blob/main/node/services/pdpConfig.ts): orchestration · Product detail page configuration helpers · `node/services/pdpConfig.ts`

### Clients

Adapters for external VTEX APIs and Intelligent Search

- [Search API](https://github.com/vtex-apps/search-resolver/blob/main/node/clients/search.ts): vtex client · Catalog and search backend adapter · `node/clients/search.ts`
- [Checkout API](https://github.com/vtex-apps/search-resolver/blob/main/node/clients/checkout.ts): vtex client · Checkout and pricing-related backend adapter · `node/clients/checkout.ts`
- [Rewriter](https://github.com/vtex-apps/search-resolver/blob/main/node/clients/rewriter.ts): vtex client · URL and query rewriting adapter · `node/clients/rewriter.ts`
- [Intelligent Search](https://github.com/vtex-apps/search-resolver/blob/main/node/clients/intelligent-search-api.ts): integration · Specialized Intelligent Search integration path · `node/clients/intelligent-search-api.ts`

### Shared

Common utilities, compatibility, and feature control

- [Compatibility](https://github.com/vtex-apps/search-resolver/blob/main/node/commons/compatibility-layer.ts): legacy layer · Legacy behavior and request compatibility handling · `node/commons/compatibility-layer.ts`
- [Feature flags](https://github.com/vtex-apps/search-resolver/blob/main/node/featureFlags.ts): runtime flags · Conditional behavior and rollout control · `node/featureFlags.ts`
- [Utilities](https://github.com/vtex-apps/search-resolver/blob/main/node/utils/index.ts): domain helpers · Shared search, category, slug, cookie, and fallback helpers · `node/utils/index.ts`

### Ops

Deployment, packaging, and test support

- [Mocks & tests](https://github.com/vtex-apps/search-resolver/blob/main/node/mocks/contextFactory.ts): test support · Colocated tests and mock fixtures protecting contracts · `node/mocks/contextFactory.ts`
- [Deployment](https://github.com/vtex-apps/search-resolver/blob/main/manifest.json): vtex packaging · App manifest, service config, and VTEX deployment metadata · `manifest.json`

## Connections

- App entry → Resolvers: wires · Initializes resolver runtime
- Resolvers → Search resolvers: routes · Search schema fields
- Resolvers → Stats resolvers: routes · Stats schema fields
- Resolvers → Benefits resolvers: routes · Benefits schema fields
- Search resolvers → Product service: delegates · Product and SKU resolution
- Search resolvers → Search service: delegates · Search result resolution
- Search resolvers → Facets service: delegates · Facet and metadata resolution
- Search resolvers → Autocomplete: delegates · Autocomplete resolution
- Search resolvers → Settings: reads · Uses configured search behavior
- Search resolvers → PDP config: reads · Uses PDP-specific configuration
- Stats resolvers → Search service: reads · Counts and query stats
- Benefits resolvers → Product service: delegates · Benefit lookups use product context
- Product service → Search API: calls · Fetches catalog and search data
- Product service → Checkout API: calls · Enriches with pricing and checkout data
- Search service → Search API: calls · Queries search backend
- Search service → Rewriter: calls · Resolves rewritten URLs
- Search service → Intelligent Search: optionally uses · Uses Intelligent Search when enabled
- Facets service → Search API: calls · Builds facet trees from search data
- Autocomplete → Intelligent Search: optionally uses · Prefers Intelligent Search suggestions when configured
- Search resolvers → Directives: uses · Applies schema-level transforms
- Stats resolvers → Directives: uses · Applies schema-level transforms
- Product service → Compatibility: adapts · Maintains legacy request behavior
- Search service → Compatibility: adapts · Normalizes legacy search semantics
- Search service → Feature flags: checks · Selects conditional behavior paths
- Product service → Utilities: uses · Shared normalization helpers
- Search service → Utilities: uses · Shared search and string helpers
- Facets service → Utilities: uses · Category and search-state helpers
- Directives → Utilities: uses · URL and asset transforms
- Mocks & tests → Search resolvers: covers · Resolver contract tests and fixtures
- Mocks & tests → Product service: covers · Service behavior tests and mocks
- Mocks & tests → Utilities: covers · Utility-level contract tests
- Deployment → App entry: packages · Deploys the Node app as a VTEX service
- Deployment → Resolvers: exposes · Publishes the GraphQL surface