Search Results Sorting

Free — GPL coresize Mplanned, not built

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

Search Results Sorting is a core feature that provides sort options for search results (price, newest, popularity, rating). It lets customers find products by preferred criteria, increasing conversion.

The problem

Customers search and can’t sort by price or popularity; they leave to check competitors.

What it does

• Sort by relevance (default), price (ascending/descending), newest, popularity, rating, best sellers
• Dropdown or button UI for sort selection with remember last sort (session storage)
• Admin setting: enable/disable sorts, default sort order (e.g., ‘relevance’)
• Mobile support: sort dropdown/modal
• Configurable per-content type (products, categories)

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 custom sort fields (reason: limited to predefined)
• Does NOT track sort usage (reason: analytics feature)
• Does NOT support alphabetical sort (reason: low priority)

Data model

No new tables. New field: settings.search_default_sort (enum). New field: products.popularity_score (float, derived from views/purchases).

API

• GET /api/search?q=shirt&sort=price_asc
• GET /api/search?q=shirt&sort=popularity
• PATCH /api/settings/search-sorting {default_sort, enabled_sorts}

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

Admin

Settings: default sort order, enable/disable sorts (subset of: relevance, price, newest, popularity, rating); preview showing results sorted by each.

The seam — why this is core

Core owns: sort API, sort options settings. Frontend owns: sort UI, session storage.

Core owns the interface + honest sort implementation; search UX is storefront infrastructure, not a support commitment or credential.

Dependencies

• Assumes search API exists
• Assumes product.popularity_score computable
• Assumes product.rating 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?q=shirt&sort=price_asc returns low to high
• GET /api/search?q=shirt&sort=price_desc returns high to low
• GET /api/search?q=shirt&sort=newest returns by created_at descending
• GET /api/search?q=shirt&sort=rating returns by average rating descending
• GET /api/search?q=shirt&sort=popularity returns by view/purchase count descending
• Sort order changeable via admin
• Sort selection persists in session
• Mobile UI: sort dropdown/modal works on touch
• Default sort is ‘relevance’ (changeable)
• All storage drivers support equally

Risks

Popularity staleness: score outdated if not real-time. Rating bias: few 5-star ratings rank high. Performance: 100k+ products need pre-computed popularity_score. User confusion: too many sorts (>5) confuses customers.

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.