quicknotes/specs/omnisearch.md

Omnisearch Specification

Overview

The Omnisearch domain provides a unified full-text search functionality across all domains of the QuickNotes application. It allows users to perform text searches on notes, feed entries, read later items, and uploaded PDF documents, and returns a list of results that link to the appropriate detail pages.

Architecture and Components

Full-Text Search Engine

To support full-text search, a search engine such as Bleve can be integrated into the backend. Bleve is a full-text search and indexing library for Go and is well-suited for this purpose.

Indexing

The following content types will be indexed for search:

• Notes: Index title and content
• Feed Entries: Index title, summary, and full content
• Readlater Items: Index title, description, and content
• Documents: Extract text from PDF documents (using an OCR or PDF text extraction tool, if necessary) and index the extracted content

API Endpoints

Method	Endpoint	Description
GET	/api/search	Perform a full-text search across all domains

Search API

• Accepts a query parameter (e.g., q) containing the search text.
• Optionally accepts pagination parameters (e.g., limit and offset).
• Returns a list of search results, each containing:
  • Type: Indicates the domain (note, feed entry, readlist item, document)
  • ID: The identifier of the result
  • Title/Name: The title or name of the result
  • Snippet: A short excerpt showing the context of the match
  • Link: A URL to the relevant detail page

Example response:

[
  {
    "type": "note",
    "id": "note-id",
    "title": "Note Title",
    "snippet": "... matching text ...",
    "link": "/notes/note-id"
  },
  {
    "type": "feed-entry",
    "id": "entry-id",
    "title": "Entry Title",
    "snippet": "... matching text ...",
    "link": "/feeds/entries/entry-id"
  }
]

Frontend Integration

Omnisearch Page

The frontend will feature a dedicated Omnisearch page with the following components:

1. Search Input: A single input field where users can enter their search query.
2. Search Results List: A list that dynamically displays the search results returned by the API.
3. Result Filtering: (Optional) Filters to narrow down results by domain (notes, feed entries, readlist items, documents).

Navigation to a result should route the user to the corresponding detail page:

• Notes: /notes/:id
• Feed Entries: /feeds/entries/:id (or /feeds/:id for feed-specific views)
• Readlist Items: /readlist/:id
• Documents: A new page (e.g., /documents/:id) for viewing the PDF using the integrated PDF viewer.

Implementation Considerations

1. Indexing Strategy: Index updates should occur whenever content is created, updated, or deleted. This may be triggered in the service layers of each domain.
2. Extraction for Documents: For PDFs, text extraction might be performed using tools like pdfcpu or similar to convert PDF content into text for indexing.
3. Performance: Ensure that the indexing and search queries are performant. Consider asynchronous indexing and regular index updates.
4. Scalability: Although Bleve works well for local deployments, evaluate if a more robust search solution is needed as the application scales.

Summary

The Omnisearch feature provides a unified search experience, leveraging full-text indexing with Bleve to search across all content domains. It improves usability by allowing users to quickly find information regardless of its domain, with results linking to the appropriate detail pages.