WaveSearch Labs: Indexing, Search, and Recommendations

This document explains how product data is indexed, how search and recommendations APIs are executed, and how the demo platform is composed and operated.

Demo-only AKS dev overlay In-cluster Kaniko builds Zero-trust tokens via STS

Architecture (runtime)

Control Plane

wave-sts: issues and validates audience-scoped JWT tokens.
wavesearch-frontend: operator UI for ingest, query tests, merchandising rules, and analytics.

Commerce Plane

wavestore-erp-api: source of truth for products, stock, pricing, orders, and export catalog.
wavestore-frontend: shopper UI with basket module, checkout module, account module, and ERP order placement.

Search Plane

wavesearch-api: indexing runtime, query API, recommendation API, events pipeline, and admin controls.
Ingress (nginx): host/path routing through one shared public IP.

Modular integration boundaries

Storefront modules

Basket module: local basket state, quantity controls, totals, and checkout payload construction.
Checkout module: calls POST /v2/checkout and persists placed orders to account history.
Account module: sign-in via STS and order history via GET /v2/account/orders.
Promotions module: loads ERP offers via GET /v2/offers; banner click applies offer query/category/productIds and executes storefront search.

ERP modules

Order module: POST /erp/orders validates items, prices from ERP pricing state, decrements stock, and creates invoice.
Catalog module: /erp/products, /erp/stock, /erp/pricing, /erp/offers, /erp/export/catalog.

Search modules

Ingest module: /search/ingest/from-erp materializes catalog snapshots into runtime indexes.
Query module: /search/query handles retrieval + facets.
Merchandising module: /search/admin/rules applies boost/bury/pin controls at ranking time.

How indexing works

Catalog data originates in wavestore-erp-api and is exported via /erp/export/catalog.
WaveSearch ingests via POST /search/ingest/from-erp with tenant and token context.
The API snapshots product JSON and rebuilds in-memory runtime indexes for low-latency query and recommendation execution.
Merchandising controls (boost/bury rules) are appended through admin APIs and applied at ranking time.

Search and recommendations APIs

Search

POST /search/query with query text, optional filters, and page size.
Requires search.query scope.
Returns ranked products with facets and metadata from indexed catalog fields.

Recommendations

POST /search/recommend with productId, visitorId, and page size.
Uses catalog relationships and behavior signals to produce related products.
Also requires search.query scope.

Operational APIs

POST /search/events for click/search telemetry ingestion.
GET /search/admin/analytics for click-through and usage summaries.
POST /search/admin/rules for boost/bury controls.

How results are generated (user-level view)

Search: when a shopper types a query, WaveSearch finds matching products from the indexed catalog, applies in-stock and merchandising signals, then returns a ranked list.
Recommendations: when a shopper views a product or browses history, WaveSearch returns similar or related products using product relationships and behavior cues.
Facets: the system aggregates the matched set into facet buckets (such as category, brand, availability) so users can refine quickly.
Metadata: each result carries product fields from the index (title, description, price, inventory, brand/category/tags, image links) so UIs do not need extra lookup calls per card.
Clickstream: user actions (search, click, view) are ingested via /search/events and summarized for analytics and ranking tuning.

How results are generated (implementation-level deep dive)

Search ranking pipeline

Candidate generation: tokenize query; retrieve candidate products from in-memory runtime indexes.
Base scoring: compute relevance score from term overlap / backend rank.
Merchandising adjustments: apply boost/bury/pin actions from admin rules.
Inventory adjustment: penalize out-of-stock and slightly uplift healthy in-stock items.
Filter + sort: apply category/brand/availability/price/stock filters and finalize ranking.

Facets and metadata return shape

Facets are computed from the final result set using indexed fields (category, brand, availability counters).
Result documents include product metadata copied from indexed catalog snapshots plus overlayed stock/pricing context.
This enables one response to populate cards, filters, and status badges in the storefront.

Recommendations pipeline

Input context: productId and optional visitor context.
Candidate generation favors related categories/brands and known similarity relationships.
Scoring reuses merchandising + availability controls so recommendations respect boost/bury and stock posture.

Clickstream ingestion and usage

Storefront posts events to POST /search/events (search, click, view, etc.).
WaveSearch appends events to the tenant/partition append-log for durable replay and auditability.
In-memory counters/analytics are updated and surfaced via GET /search/admin/analytics.
Signals are used for operator decisions (boost/bury tuning, no-result diagnosis, promo effectiveness checks).
On rebuild/recovery, durable snapshots + append logs can reconstruct state and analytics context.

Key design assumptions

This environment is demo-only and deploys dev overlay replicas.
All services are independently deployable but run as one logical platform behind shared ingress.
Authentication is mandatory: bearer token + tenant header + audience/scope checks.
For this ARM AKS cluster, images are built in-cluster with Kaniko and pushed to ACR.
Ingress remains centralized: per-service hostnames route through the same ingress public IP.

Prompt to rebuild the platform from scratch

Use this prompt with Copilot/agent mode to recreate the stack end-to-end:

Build a demo-only enterprise retail search system (Vertex Retail Search equivalent behavior) on AKS using OSS components, with no Azure AI Search dependency.

Business intent:
- Showcase reusable demo architecture with clear service boundaries.
- Support dynamic facets, boost/bury merchandising, recommendations, and analytics.
- Run as a dev-only environment (no production store topology).

Create these six deployable services:
1) wave-sts (auth service): issue/validate short-lived JWTs with audience + scope enforcement.
2) wavestore-erp-api: source of truth for products, stock, pricing, offers, customers, orders, invoices; expose /erp/export/catalog.
3) wavesearch-api: ingest catalog from ERP; provide /search/query, /search/recommend, /search/events, /search/admin/*.
4) wavestore-frontend: shopper UI (Bootswatch style) for search, recs, basket, order placement.
5) wavestore-erp-frontend: WaveFunction/BareMetalJsTools style ERP admin GUI.
6) wavesearch-frontend: WaveFunction/BareMetalJsTools style search ops GUI + platform docs pages.

Functional requirements:
- Zero-trust everywhere: bearer token required, X-Tenant-Id required, tenant header/token match required.
- Enforce audience-scoped tokens and route-level scopes (no implicit admin bypass).
- Search supports keyword retrieval + facets + merchandising boost/bury controls.
- Recommendations endpoint supports product/visitor context and returns priced products.
- Events endpoint captures click/search telemetry; admin analytics endpoint summarizes behavior.
- ERP-to-search ingestion path: POST /search/ingest/from-erp using ERP export + token.

Platform and deployment constraints:
- AKS namespace: wave-dev only.
- Single shared ingress controller/public IP; host-based routing under retail.demos.wavefunctionlabs.com.
- Required hosts:
  store.retail.demos.wavefunctionlabs.com
  erp.retail.demos.wavefunctionlabs.com
  labs.retail.demos.wavefunctionlabs.com
  sts.retail.demos.wavefunctionlabs.com
  search-api.retail.demos.wavefunctionlabs.com
  erp-api.retail.demos.wavefunctionlabs.com
  orchestrator.retail.demos.wavefunctionlabs.com
- Build images in-cluster with Kaniko (ARM node compatible), push to ACR, then rollout.
- Do not rely on remote CI builds for demo deploys.

Documentation/UI deliverables:
- Demo orchestrator page linking all UIs and service endpoints, with architecture summary.
- Platform guide page explaining indexing flow, APIs, design assumptions, and rebuild prompt.
- README + deployment runbook with build/deploy/health/smoke commands.

Validation criteria:
- All six deployments healthy in wave-dev.
- Ingress routes live on shared IP.
- Search, recommend, ingest, analytics, and order flows callable end-to-end.
- Frontend style policy: Bootswatch for storefront/search page; WaveFunction style for other GUIs.