Feature: Search Feature Implementation (FEAT-58)

Metadata

  • Issue ID: FEAT-58
  • Status: Done
  • Owner: Kzu0-afk
  • Related PRs: TBD
  • Canonical feature doc: docs/features/FEAT-58-Search-Feature-Implementation.md

Overview

FEAT-58 improves search and ranking quality across discovery surfaces:

  • Explore page
  • Institutions directory
  • Courses directory
  • Documents directory

The objective is stronger discoverability and monetization support while preserving relevance, stability, and SEO-friendly behavior.

Frontend Behavior

  • Uses URL-driven search state (q, sort, page) on directory pages for shareability and crawl consistency.
  • Keeps entity-specific search + sort controls with clear empty-result and fallback states.
  • Preserves active filters across pagination links.
  • Maintains current Explore-page strategy:
    • lightweight client-side filter for preloaded cards in v1;
    • deeper backend-powered search integration planned for follow-up phase.
  • Allows optional local persistence only for non-sensitive UX preferences (recent query/sort context), with URL state remaining authoritative.

Backend Behavior

  • Existing catalog APIs already support paginated query + sort:
    • GET /institutions
    • GET /courses
    • GET /documents
    • plus scoped variants (/institutions/:slug/courses, /courses/:slug/documents)
  • Ranking/signals currently used:
    • documents: quality, downloads, views, trending/engagement, topic tags
    • courses: popularity, document depth, trending
    • institutions: course/document breadth and location/name relevance
  • FEAT-58 planning includes continued relevance tuning, deterministic tie-breakers, and bounded query behavior.

QA Test Scenarios

Scenario IDDescriptionStepsInputExpected Result
FEAT-58-01Happy-path document searchOpen /documents, search for known termq=<known term>Relevant items appear with stable sorting/pagination
FEAT-58-02Validation fallback sortForce unsupported sort valuesort=unknownAPI/UI falls back safely to default sort
FEAT-58-03Backend failure handlingSimulate upstream/API failuren/aPage shows resilient fallback state, no crash
FEAT-58-04Edge no-match stateSearch nonexistent queryq=<nonexistent>User sees clear no-results state

For the full scenario matrix and detailed QA notes, see:

  • docs/features/FEAT-58-Search-Feature-Implementation.md

Edge Cases

  • Long or symbol-heavy queries.
  • Query/sort persistence across pagination transitions.
  • URL vs localStorage preference mismatch (URL wins).
  • Ranking drift when engagement signals update between page loads.
  • Explore-page partial preload vs deep catalog search expectations.

Notes

  • This SBDocs page is a compact index view; the canonical implementation details remain in the FEAT-58 feature doc.
  • No mock/placeholder search data is introduced.
  • No auth/session model changes are part of FEAT-58 search scope.