Search Filters & Facets

Free — GPL coresize Lplanned, not built

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

Search Filters & Facets is a core feature that adds filtering capabilities to search results. It lets customers narrow lists by price, brand, size, and other attributes, reducing choice paralysis.

The problem

Search results show 5,000 products; customers can’t filter by price, brand, or size and abandon.

What it does

• Faceted search: aggregate counts by attribute (price, brand, color, size) with multi-select AND logic
• Price range filter: slider or input (min/max) and category filter (checkbox)
• Brand, size, color filters with visual color swatches
• Filter by availability: in-stock only
• Admin settings: choose filterable attributes per category
• URL parameters: bookmarkable filter state (?size=M&color=red&price_min=10&price_max=50)
• Mobile UI: collapsible filters

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 facet hierarchies (reason: complexity)
• Does NOT support OR logic (reason: AND logic only)
• Does NOT auto-suggest filter combinations (reason: separate feature)
• Does NOT support saved filter sets (reason: separate feature)

Data model

New table: filterable_attributes (id, name, type, category_id, order). New table: attribute_values (id, attribute_id, value, color_hex, order). New dynamic fields on products: size, color, brand, etc.

API

• GET /api/search?q=shirt&filters=size:M,color:red&price_min=10&price_max=50
• GET /api/search/facets?q=shirt
• GET /api/search/facets/:attribute
• GET /api/categories/:id/facets

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

Admin

Category edit: select filterable attributes; attribute management (add/edit/delete); facet dashboard showing most-used filters; reorder facets.

The seam — why this is core

Core owns: facet storage, filter API, facet counting. Frontend owns: filter UI rendering.

Core owns the interface + honest faceted search; product filtering is core infrastructure, not a per-country obligation or credential.

Dependencies

• Assumes product attributes exist
• Assumes search API exists
• Assumes filtering supported by 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/facets?q=shirt returns {size: {S: 10, M: 25, L: 20}, color: {red: 15, blue: 30}}
• Facet counts accurate (match filtered results)
• Filters combined: size=M AND color=red returns products in both
• Price range: price_min=10&price_max=50 returns in range
• Availability: in_stock=true returns available only
• Bookmarkable: URL with filters can be shared
• Facet counts update when filters applied
• Mobile UI: filters collapsible
• All storage drivers support equally
• Admin can mark attributes filterable per category

Risks

Facet count accuracy: products with multiple sizes overstated. Performance: 100k+ products slow without indexing. Schema migration: adding tables and dynamic attributes. Facet explosion: 100+ attributes bloats UI.

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.