Search Analytics

Free — GPL coresize Mplanned, not built

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

A dashboard that shows merchants which search terms customers use, which searches fail (return no results), and trends over time. Merchants can optimize product names and identify missing inventory based on what customers are actually looking for.

The problem

Merchants have no visibility into what customers search for. They can’t tell if a popular search is failing, can’t optimize product names to match customer language, and can’t identify missing SKUs that would drive revenue.

What it does

• Log every customer search query: search text, filters applied, result count, timestamp, shop ID
• Track failed searches (queries that return zero results)
• Display top searches by frequency with result counts
• Show trending searches (queries gaining velocity week-over-week)
• Filter analytics by date range (last 7 days, last month, custom)
• Connect searches to order data: show which searches led to completed orders vs. abandoned
• Expose search queries via REST API for merchants building custom dashboards
• Do not log staff/admin searches (only customer searches)
• Export search analytics as CSV with timestamp, query, result count, conversion status
• Provide webhooks when notable patterns occur (search with zero results logged)

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 recommend keywords or product tags automatically — that’s merchant content ownership and prevents over-automation of product data.
• Does not offer auto-complete or search suggestions for customers — that’s the ‘product-search-ai-semantic-discovery’ paid module.
• Does not segment searches by customer cohort or RFM tier — that’s paid CRM analytics, not core infrastructure.
• Does not A/B test search result ranking — that’s a separate paid experimentation module.
• Does not integrate with external analytics platforms (Google Analytics, Mixpanel) — that’s integration layer, paid or community-owned.

Data model

New table SearchQuery: id (string), shopId (string), customerId (nullable string), queryText (string), filters (JSON object), resultCount (integer), createdAt (ISO datetime). Optional rollup table SearchAnalyticsSummary for performance: shopId, date, topQueries (JSON), failedQueryCount (integer). No migration required if added to new shops; existing shops add table on upgrade.

API

• GET /admin/search-analytics/queries — paginated list of logged queries
• GET /admin/search-analytics/queries?search=… — filter queries by text substring
• GET /admin/search-analytics/queries?dateFrom=ISO&dateTo=ISO — filter by date range
• GET /admin/search-analytics/summary — returns top/failed/trending queries
• GET /admin/search-analytics/export?format=csv — CSV download

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

Admin

Dashboard page titled ‘Search Analytics’ showing: (1) top 10 searches by frequency with result counts; (2) failed searches count and list; (3) trending searches (velocity over last 7/30 days); (4) date range picker to filter all metrics; (5) conversion funnel: % of top searches that led to orders; (6) export CSV button; (7) refresh timestamp showing when data was last updated.

The seam — why this is core

Core owns the search query logging interface, data storage across all drivers (lowdb/libSQL/SqlStorage), analytics aggregation logic, and dashboard UI. No paid module — this is infrastructure. Paid modules (like product-search-ai-semantic-discovery) may consume this data but do not own it.

Core owns the interface + honest query logger; search insights are infrastructure, not a per-country obligation or credential.

Dependencies

• Product search backend (existing)
• Customer system (to link customerId to searches)
• Webhook/event system (to trigger on zero-result queries)
• Order fulfillment system (to connect searches to purchased products)

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.

• A search query with resultCount=0 appears in the ‘failed searches’ section and is counted in failedQueryCount
• Staff/admin searches (users with staff role) do not appear in search analytics at all
• Top 10 searches are sorted by frequency (highest first) and list the search text and result count
• Date range filter with dateFrom=2025-01-01 and dateTo=2025-01-31 excludes all queries outside that range
• Export CSV file contains columns: timestamp, query, resultCount, shop, customerId, and has one row per logged query
• Search query logging adds <10ms latency to the customer search response (measured end-to-end)
• Trending searches list includes a ‘velocity’ metric or week-over-week change percentage
• Search analytics dashboard returns results in <500ms even with 100,000 logged queries in the shop

Risks

If query logging is asynchronous and silently fails, merchants believe searches are working but no analytics are recorded, blocking optimization. If staff searches leak into analytics, the data is polluted and trends are untrustworthy. If CSV export includes customerId without proper permission checks, it may expose customer privacy. If analytics are not eventually consistent across storage drivers, results differ by driver, causing debugging confusion.

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.