Fuzzy Search

Free — GPL coresize Mplanned, not built

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

Fuzzy Search is a core feature that handles typos and misspellings in product searches. It uses edit distance to suggest correct product names even with 1-2 character mistakes.

The problem

Customers searching ‘shert’ instead of ‘shirt’ get zero results; they leave instead of browsing.

What it does

• Typo tolerance: accept queries with 1-2 edit distance errors (Levenshtein or Damerau-Levenshtein)
• Configurable tolerance level (strict: 1 edit, lenient: 2 edits)
• Suggest correct spellings (e.g., ‘shert’ → ‘shirt’)
• Fall back to exact match if fuzzy match yields no results
• Fuzzy search on product name, category name, tags
• Performance: fuzzy search <500ms for 100k+ products
• Admin setting: enable/disable fuzzy search, tolerance level

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 phonetic matching (reason: language-specific)
• Does NOT provide ML-based typo correction (reason: separate AI feature)
• Does NOT track typo patterns (reason: analytics feature)
• Does NOT support custom typo dictionary (reason: admin burden)

Data model

No new tables (fuzzy matching computed on-the-fly). New fields: settings.fuzzy_search_enabled (bool, default: true), settings.fuzzy_search_tolerance (enum: ‘strict’, ‘lenient’, default: ‘lenient’).

API

• GET /api/search?q=shert&fuzzy=true
• GET /api/search/fuzzy-match?q=shert
• PATCH /api/settings/fuzzy-search {enabled, tolerance}

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

Admin

Settings toggle (enable/disable); tolerance slider; preview searching for typo; stats showing % of searches using fuzzy.

The seam — why this is core

Core owns: fuzzy matching algorithm, API, settings.

Core owns the interface + honest typo-tolerant search; search quality is infrastructure, not a support commitment or credential.

Dependencies

• Assumes basic product search exists (fallback)
• Assumes all storage drivers support string comparison

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 ‘shirt’ in top 3 (Levenshtein distance 1)
• Query ‘teh’ returns ‘the’
• Tolerance changeable strict (1) to lenient (2)
• Can be disabled via admin
• Results include ‘Did you mean: shirt?’
• Returns results <500ms for 100k+ products
• All storage drivers support equally
• Typo words with distance >2 don’t trigger fuzzy match

Risks

False matches: ‘cat’ fuzzy matches ‘car’. Performance: Levenshtein O(n*m) slow. Language bias: poor for diacritics. Over-matching: lenient tolerance too many false positives.

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.