Basic Product Search

Free — GPL coresize Lplanned, not built

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

Merged from duplicate proposals: “Basic Product Search”, “Advanced Product Search”

Basic Product Search is a core feature that provides a simple, built-in search for products by name, description, and SKU. It enables customers to quickly find products without browsing categories.

The problem

Customers can’t find products by name; they either browse forever or leave.

What it does

• Full-text search on product name, description, SKU, tags (case-insensitive, diacritic-insensitive)
• Pagination: 20 results/page with next/prev navigation and sort (relevance, newest, price)
• Search results page: product name, image, price, rating
• Search bar on all pages (header, mobile menu) with search history (5-10 recent queries)
• Empty search handling: show featured products or categories
• No results handling: show ‘Did you mean?’ or suggestion
• Admin settings: configure search behavior

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 (reason: separate fuzzy-search feature)
• Does NOT support faceted filtering (reason: separate search-filters-facets feature)
• Does NOT support advanced query syntax (reason: separate advanced-search feature)
• Does NOT track search analytics (reason: separate analytics feature)

Data model

New table: search_queries (id, query, result_count, created_at) [optional metrics].

API

• GET /api/search?q=shirt&page=1&sort=relevance
• GET /api/search/suggestions?q=shi
• GET /api/search/stats

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

Admin

Search settings (case-sensitivity, diacritics); analytics (top queries, avg results); no results queries showing improvement opportunities.

The seam — why this is core

Core owns: search indexing, query API, basic ranking.

Core owns the interface + honest search implementation; product discovery is core infrastructure, not a credential, per-country obligation, or support commitment.

Dependencies

• Assumes product name, description, SKU, tags exist
• Assumes full-text search on storage driver

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?q=shirt returns products with ‘shirt’ in name/description
• Results sorted by relevance (name matches ranked higher)
• Pagination works: page=1 shows first 20, page=2 shows next 20
• Sort by price works (ascending/descending)
• Search results include name, image, price, rating
• Case-insensitive: SHIRT, Shirt, shirt return same
• Diacritic-insensitive: café and cafe return same
• Empty search shows featured products or categories
• Search suggestions show previous 5 queries
• No results shows ‘Did you mean?’ if similar products exist

Risks

Performance: 100k+ products without indexing slow. Relevance tuning: name should rank higher than description. Diacritic normalization: may not work for Arabic, CJK. Stop words cause noise.

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.