marketplaces/docs/Search.md

Search Intelligence Engine - Sprint 12

Scope

Sprint 12 introduces a standalone Search Feature architecture reusable across marketplaces.

Constraints respected:

• No authentication changes
• No payment changes
• No runtime bootstrap changes
• No Widget Manifest changes
• No Section Engine changes
• No Product/Catalog business rule changes

Architecture

src/app/features/search/
  components/
    search-bar/
    trending-searches/
    empty-results/
  services/
    search-autocomplete.service.ts
    search-history.service.ts
    search-history.repository.ts
    search-trending.service.ts
    search-cache.service.ts
    search-analytics.service.ts
  facade/
    search.facade.ts
  models/
    search.model.ts
    search-state.model.ts
  store/
    search.store.ts
  utils/
    search-query-key.util.ts

Legacy compatibility kept:

• src/app/facades/platform/search.facade.ts now re-exports feature facade
• src/app/core/search/models/* re-export feature models
• src/app/core/search/services/search-history.service.ts re-exports feature history service

Facade API

Search UI communicates through SearchFacade:

• search(query)
• loadCatalog(query)
• suggestions(query, products, categories, limit)
• autocomplete(query, products, categories, limit)
• getSearchHistory()
• pushSearchHistory(term, maxHistory)
• clearSearchHistory()
• trending()
• existing helpers reused by catalog: filters, sorting, pagination, query params

State Model

Managed in SearchStore:

• current query
• loading
• results
• suggestions
• recent searches
• popular searches
• selected filters
• current sort
• current page
• total results

Compatibility aliases preserved for existing catalog integration.

Suggestion Model

Each suggestion includes:

• type
• title
• subtitle
• icon
• target

Supported suggestion types:

• product
• category
• brand
• collection
• seller
• static-page
• ai

Autocomplete

Behavior:

• Debounced typing (debounceTime)
• Previous request cancellation (switchMap)
• Distinct query suppression (distinctUntilChanged)
• Suggestion state controlled by facade/store

Current source:

• In-memory products/categories/tags

Future-ready for backend endpoint:

• autocomplete service can switch to API provider without UI changes

Search History

Abstraction:

• SearchHistoryRepository
  • LocalSearchHistoryRepository for guest users
  • BackendSearchHistoryRepository placeholder for logged users

Behavior:

• Newest first
• Configurable max length
• Clear history support

Trending Searches

SearchTrendingService contract introduced.

Current behavior:

• Returns null when endpoint unavailable
• UI hides trending block gracefully

Empty Results UX

Reusable empty state supports:

• no results messaging
• popular categories
• popular searches
• recommended products
• reset filters action

Filters and Sorting Reuse

No duplicated filter/sort engines.

Search facade reuses existing catalog filter metadata generation, filter application, and sort application pathways.

Search Bar UX

Reusable SearchBarComponent supports:

• ESC closes suggestions/overlay
• arrow navigation
• Enter opens highlighted suggestion
• mouse selection
• loading indicator
• clear button
• mobile fullscreen overlay with large touch targets

Performance

Implemented:

• debounce
• switch-map cancellation
• duplicate suppression
• query-result cache for repeated searches

Analytics Architecture

SearchAnalyticsService provides event factory only.

Event shape:

• query
• tenant
• language
• timestamp
• result count

No analytics transport implementation in Sprint 12.

Configuration and Extension Points

Extension points:

• replace history repository with backend endpoint
• replace trending provider with backend endpoint
• replace autocomplete provider with API or AI provider
• enrich suggestion mapper with static pages/sellers/collections sources

Responsiveness and Accessibility

• Desktop suggestion dropdown behavior
• Mobile fullscreen overlay behavior
• ARIA labels and keyboard navigation
• touch target sizing in mobile mode