Search & Saved Views
Relevant source files
The following files were used as context for generating this wiki page:
Search & Saved Views enable users to query their research library and persist specific search definitions for later reuse. Unlike static collections, Saved Views store search parameters rather than result snapshots, ensuring that views remain dynamic as the library grows.
The system integrates a full-text search engine with bibliographic metadata filtering. The frontend uses a specialized codec to translate between application routes, URI fragments, and internal search definitions, maintaining parity between manual searches and persisted views.
Sources: README.md:14-36, backend/AGENTS.md:58-61
Search Architecture
The search system processes queries through several layers, from URI parsing in the browser to full-text indexing in the backend.
Query Codec
The codec.ts module manages the conversion of search parameters. It translates route parameters into a structured search definition that the API consumes. The codec ensures that parameter ordering remains stable to produce canonical URL hashes.
Sources: frontend-app/src/features/search/codec.test.ts:4-100, tests/test_frontend_saved_views.py:166-170
Search Modes
The system supports three primary search modes, which determine which fields the engine queries:
| Mode | Parameters | Description |
|---|---|---|
| All | q, any=1 | Broad search across titles, notes, and PDF text. |
| Advanced | q, author, publisher | Explicit filtering on specific bibliographic fields. |
| Tag | tag, author, publisher | Filter by a primary tag while optionally filtering by author or publisher. |
Sources: frontend-app/src/features/search/codec.test.ts:41-80, frontend/index.html:620-630
Data Flow for Search
The following diagram illustrates how a user request traverses the system:
The Search and Saved View detail surfaces share a single result boundary, using the same coordinator read and result collection components to ensure consistent rendering.
Sources: tests/test_frontend_saved_views.py:84-95, tests/e2e/test_search_saved_views_route_surface.py:35-60
Saved Views Lifecycle
Saved Views are online-only entities that persist named search definitions. They do not store work membership directly.
Persistence and Operations
Saved Views are managed through the /api/saved-views endpoint. The backend enforces limits on the maximum number of views per library and ensures name uniqueness.
| Endpoint | Method | Purpose |
|---|---|---|
/api/saved-views | GET | Lists all Saved Views, ordered case-insensitively by name. |
/api/saved-views | POST | Creates a new named search definition. |
/api/saved-views/{id} | PATCH | Renames a view or updates its search parameters. |
/api/saved-views/{id} | DELETE | Removes the view definition without affecting library files. |
Sources: backend/api_contract/openapi.py:345-420, tests/test_frontend_saved_views.py:118-135
Saved View Interactions
The frontend manages Saved Views through a shared SavedViewRecords service. This service handles creation, updates, and removals, notifying the UI to refresh its state.
Implementation Details
UI Components
The user interface for managing views includes several key elements:
- SavedViewModal: A shared modal used for both creating and editing view definitions.
- SavedViewsIndexRoute: A Vue-based surface that lists all views and provides management actions.
- SavedViewDetailRoute: Renders the dynamic results of a specific view, sharing logic with the standard Search route.
Sources: frontend/index.html:610-645, tests/test_frontend_saved_views.py:118-125
Constraints and Validation
- Naming: Names are limited to 80 characters.
- Search Definition: The system rejects invalid combinations, such as mixing broad "All" keywords with specific "Tag" filters in an unsavable way.
- Privacy: Search terms and view names are library metadata and are handled according to the project's metadata privacy rules.
Sources: frontend-app/src/features/search/codec.test.ts:13-35, backend/api_contract/openapi.py:382-390, backend/AGENTS.md:60-61
Conclusion
The Search & Saved Views system provides a flexible mechanism for navigating large research libraries. By separating search definitions from work membership, the system ensures that user-defined views automatically reflect the current state of the library. Consistent use of a query codec across the legacy and Vue frontend ensures stable, predictable routing and persistence.