vtex-apps/search-resolver

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.