Autocomplete Suggestions

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/autocomplete-suggestions/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Autocomplete Suggestions is a core feature that provides real-time search suggestions as customers type. It shows matching products, categories, and recent searches to help customers discover faster.

The problem

Customers don’t know what to search for; they type partial searches and get no suggestions.

What it does

• Real-time suggestions as user types (debounced, <300ms latency) with product/category/search suggestions
• Prioritize popular searches by frequency with up to 10 suggestions per request
• Keyboard navigation: arrow keys to select, enter to search
• Mobile support: dismiss keyboard on selection
• Admin settings: enable/disable, suggestion limit
• Separate suggestion types: products, categories, searches

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Does NOT support typo tolerance in suggestions (reason: separate fuzzy-search feature)
• Does NOT rank by user behavior (reason: requires ML)
• Does NOT provide autocomplete for filters/facets (reason: separate feature)
• Does NOT track suggestion clicks (reason: analytics feature)

Data model

New table: search_suggestions_cache (id, prefix, suggestions, updated_at) [performance cache].

API

• GET /api/search/autocomplete?q=shi
• GET /api/search/autocomplete?q=shi&type=products,categories
• GET /api/search/popular-searches

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Settings (enable/disable, limit); cache stats (hit rate, latency); reset cache button.

The seam — why this is core

Core owns: autocomplete API, suggestion ranking, caching. Frontend owns: keyboard nav, UI rendering, debouncing.

Core owns the interface + honest suggestion engine; search UX is storefront infrastructure, not a per-country obligation or credential.

Dependencies

• Assumes product, category, search query APIs exist
• Assumes caching layer exists

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• GET /api/search/autocomplete?q=shi returns products starting with ‘shi’
• Suggestions include products, categories, recent searches
• Popular searches ranked higher (by frequency)
• Suggestions returned within 100ms (cached)
• Keyboard nav: arrow keys select, enter submits
• Mobile: selection dismisses keyboard
• Can be disabled via admin setting
• Limit changeable 5-20
• All storage drivers support equally
• Separate sections for products/categories/searches

Risks

Cache staleness: if product renamed, old name remains until cache expires. Bias: popular searches may be typos/spam. Performance: 100k+ products slow without indexing. Privacy: popular searches may leak competitor queries.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.