# 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

```text
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