Product Search & AI Semantic Discovery

Free — GPL coresize Lplanned, not built

Generated from docs/plan/core/product-search-ai-semantic-discovery/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A two-tier search system: core provides fast keyword search with typo tolerance; a paid module adds semantic search (find ‘winter jacket’ when customer searches ‘warm coat’), synonym expansion, and personalized ranking. Together, they reduce search falloff and help customers find products even with imperfect queries.

The problem

Customers search for products but get no results or irrelevant results. Typos kill search (‘shir’ doesn’t find ‘shirt’). Synonym gaps are huge (‘pants’ doesn’t find ‘trousers’, ‘gift ideas’ doesn’t find giftable products). Customers abandon, and merchants lose sales. Competitors use AI to solve this.

What it does

• Core: Index all products by name, description, SKU, category, and custom attributes in a full-text search engine
• Core: Keyword search returns products matching one or more keywords, ranked by relevance (exact name match > partial match > description match)
• Core: Basic typo tolerance using edit distance (Levenshtein distance <= 2) so ‘shir’ finds ‘shirt’
• Core: Filter search results by category, price range, or custom attributes (faceted navigation)
• Core: Autocomplete/search suggestions showing popular search terms and product names that match the query prefix
• Core: API to retrieve search results; display results on storefront
• Paid module: Semantic search using embeddings (customer search ‘warm coat’ finds ‘winter jacket’, ‘fleece parka’)
• Paid module: Synonym database and expansion (add ‘pants’ = ‘trousers’, ‘jeans’; search applies expansions)
• Paid module: Advanced typo tolerance and phonetic matching (beyond edit distance)
• Paid module: NLP intent detection (search ‘gift for kids’ triggers giftable product tag, finds age-appropriate items)
• Paid module: Personalized ranking (if logged-in customer previously bought ‘winter coats’, rank coats higher in results)
• Paid module: Search analytics and recommendations (show top searches, failed searches, trending in admin)

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 auto-tag products based on search queries — that’s merchant content responsibility; AI tagging is a separate feature.
• Does not handle multi-language search — that’s i18n localization, paid module or separate feature.
• Does not provide visual search (image-to-product matching) — that’s a separate computer vision feature.
• Does not offer real-time inventory integration in search results — search results are eventually consistent; inventory updates lag (acceptable for UX).
• Does not recommend products to merchants — that’s a separate ‘product suggestions’ module for content optimization.

Data model

Core: ProductSearchIndex table with fields: productId (string), shopId (string), name (string), description (text), sku (string), category (string), price (integer), attributes (JSON), indexed_at (datetime). Paid module adds: ProductEmbedding table with productId, shopId, embedding (vector, e.g., 1536-dim float array), model_version (string), indexed_at. Synonyms table: shopId, term (string), synonyms (array of strings). Schema migration required on first upgrade: backfill ProductSearchIndex by scanning Products table.

API

• GET /search?q=… — keyword search
• GET /search?q=…&category=… — filtered search by category
• GET /search?q=…&priceMin=…&priceMax=… — filtered search by price range
• GET /search/suggest?q=… — autocomplete suggestions
• GET /search?q=…&semantic=true — semantic search (paid module)
• GET /admin/search/index-status — indexing status
• POST /admin/search/rebuild-index — trigger full reindex
• GET /admin/search/analytics — search analytics
• PUT /admin/search/synonyms — manage synonyms

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

Admin

Search admin page with sections: (1) Index Status showing last reindex time, product count, embedding model version; (2) Reindex button with progress indicator; (3) Test search box for manual testing; (4) Semantic search toggle (if paid module is active); (5) Synonym manager with form to add/edit synonyms (term -> synonyms); (6) Analytics card showing top searches, failed searches (0 results), and average results per query.

The seam — why this is core

Core owns: product indexing infrastructure, keyword search algorithm, basic typo tolerance (edit distance), search index storage across all drivers (lowdb/libSQL/SqlStorage), storefront search UI, autocomplete. Paid module owns: embedding model and vector indexing, semantic search algorithm, synonym management, advanced fuzzy matching, NLP intent detection, personalized ranking based on customer history, search analytics and recommendations.

Core owns product index and basic keyword matching; paid module owns vector embeddings, semantic search ML model, and typo-tolerant indexing

Dependencies

• Products table (existing)
• Product categories/attributes system (existing)
• Search event logging (for analytics)
• Customer purchase history (for personalized ranking in paid module)

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.

• Search ‘shirt’ returns all products with ‘shirt’ in name or description
• Search ‘shir’ (typo, 1 char off) finds products containing ‘shirt’
• Search results are sorted by relevance: products with ‘shirt’ in name rank above products with ‘shirt’ in description only
• Autocomplete for ‘sh’ suggests product names and popular searches starting with ‘sh’ (e.g., ‘shirt’, ‘shoes’, ‘shorts’)
• Filter search results by price range $10-50 returns only products priced in that range
• Search with no results returns empty list, not 404 error, with message ‘No products found’
• Semantic search toggle (paid): search ‘warm coat’ returns ‘winter jacket’ and ‘fleece parka’ products (if toggle is on)
• Synonym system (paid): add synonym ‘pants’ -> ‘trousers’; search ‘pants’ now also returns products tagged with ‘trousers’

Risks

If indexing is incomplete or products are skipped, they never appear in search (silent failure). If typo tolerance is too loose, ‘shirt’ matches ‘start’ (poor relevance, user frustration). If typo tolerance is too strict, ‘shir’ doesn’t match ‘shirt’ (customer leaves). If semantic embedding model is stale or crashes, semantic search falls back to keyword (acceptable, but feature is down). If synonym database is crowdsourced and unmoderated, bad synonyms break search (‘bra’ -> ‘brasserie’ is nonsense). If personalization uses client-side data, privacy concerns arise; must use server-side customer purchase history.

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.