Advanced Search (Elasticsearch)

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €49/mo; faceted search, typo tolerance, relevance tuning

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

Advanced Search is a paid plugin that integrates Elasticsearch to provide typo-tolerant, faceted, and relevance-ranked search. It handles 1000x query volume compared to native search and supports advanced filtering on product attributes.

The problem

Native search can’t handle typos, facets, or relevance tuning; I need Elasticsearch for typo tolerance and advanced filtering.

What it does

• Sync product catalog to Elasticsearch index on publish/update with zero-downtime reindexing
• Support fuzzy matching (typo tolerance with edit distance), faceted search (category, brand, price range)
• Support relevance tuning (boost product name, description, tags) and range queries (price, rating)
• Provide search suggestions/autocomplete from index
• Fallback to native search if Elasticsearch is unreachable
• Admin dashboard: index health, query volume, performance metrics

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 manage Elasticsearch infrastructure (reason: merchant responsibility, support complexity)
• Does NOT support multi-language stemming (reason: requires language-specific tokenizers, support burden)
• Does NOT provide search analytics/heatmap (reason: separate analytics tool)
• Does NOT sync to multiple indices (reason: single product index per shop)
• Does NOT expose raw Elasticsearch API (reason: JSON-only, no direct cluster access)

Data model

New table: search_index_metadata (id, index_name, version, status, product_count, last_sync_at). New table: search_queries (id, query, result_count, filters_applied, created_at) [optional metrics]. Plugin settings: elasticsearch_url, index_prefix, sync_batch_size, facets_enabled. Elasticsearch document mapping for products (name, description, price, category, tags, sku, rating).

API

• GET /api/search?q=shirt&facets=category,brand&price_min=10&price_max=100
• GET /api/search/suggestions?q=shi
• GET /api/search/facets?category=Men
• POST /api/search/reindex
• GET /api/search/status

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 (Elasticsearch URL, sync frequency); index dashboard (version, product count, last sync); reindex button with progress bar; search performance metrics; fallback mode indicator.

The seam — why this is paid

Core owns: native search implementation, product catalog API, search result rendering. Paid plugin owns: Elasticsearch integration, index management, relevance tuning, faceted search.

Support commitment: Elasticsearch cluster management, search relevance tuning, index optimization

Dependencies

• Requires external Elasticsearch cluster (self-hosted or cloud)
• Assumes product catalog is queryable via API
• Assumes product update webhooks exist (for index sync)
• Assumes core search API exists (fallback path)

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.

• Query ‘shert’ returns products matching ‘shirt’ in top 3 results
• GET /api/search?q=shirt&facets=category returns accurate facet counts
• Price range query (price_min=10&price_max=50) returns only products in range
• Search response time <200ms for 10k+ product catalog
• Query ‘red shirt’ searches across name, description, tags with title boost
• Reindex progress endpoint shows % complete (0-100)
• If Elasticsearch is down, fallback to native search with degraded results
• Search suggestions return 5-10 queries starting with prefix
• Merchant can customize facets (disable category, add brand, add size)
• All storage drivers can be indexed equally

Risks

Elasticsearch cluster cost merchant responsibility; misconfiguration causes slow queries. Index sync lag: if sync fails, old products stay indexed. Query DSL complexity: misconfigured facet names cause silent failures. Schema migration: existing search history won’t be reindexed.

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.