Feature Specification: Search & Discovery

1. Overview & Vision

Search & Discovery ensures that files and folders remain findable as organizations grow. It provides a lightning-fast, case-insensitive search mechanism that allows users to locate assets by name and metadata without navigating complex directory trees.

2. Personas & Stakeholders

Persona	Goal
User	Quickly find a document by typing a few characters of its name.
Admin	Discover assets across the entire organization for auditing.

3. User Stories

• As a user, I want to search for "Contract" and see all files with that name in my organization.
• As a member, I want to see the folder path of a search result so I know its context.

4. Functional Requirements (FR)

• REQ-SD-001: Real-time name-based file search (minimum 2-character query).
• REQ-SD-002: Search results include folderId for context navigation.
• REQ-SD-003: Recent search history per user (planned for v1.2).

5. Non-Functional Requirements (NFR)

• Latence: Search response < 300ms for up to 100,000 items.
• Scalability: Support for complex multi-attribute queries.

6. Business Logic & Rules

• Organization Scope: Results are strictly limited to the user's organizationId.
• Case Insensitivity: Search terms are treated as case-insensitive (ILIKE %q%).
• Minimum Length: Queries shorter than 2 characters are ignored.
• Pagination: Default limit of 50 results; supports limit and offset parameters.

7. User Interface (UI/UX)

• Search Bar: Persistent top-bar input with "Clear" and "Recent" icons.
• Dropdown Results: Instant preview of top 5 results as the user types.
• Full Results Page: Dedicated view with advanced filters and pagination.

8. Information Architecture

• Global search accessible from any folder view.
• Search result cards show: Icon, Name, Folder Path, and Size.

9. Data Model & Persistence

• Tables: files, folders.
• Index: GIN or B-tree indexes on name and org_id columns.

10. API & Service Layer

• GET /api/files?q=term — name search (min 2 chars), supports folderId, limit, offset

11. Integration Patterns

• Shell Link: (Future) Shell global search can query the Drive search API via gRPC.

12. Security & Permissions

• RBAC: drive:read required to perform searches.
• Privacy: Only metadata is searched (File content search is planned for v2 using the AI Assistant's vector store).

13. Error Handling & Resilience

• Friendly "No results found" state with tips for better searching.
• Rate limiting for high-frequency search requests.

14. Performance & Scalability

• Uses database-level full-text search features where applicable.
• Result limiting (Top 50) to prevent UI lag.

15. Globalization & i18n

• Support for searching Vietnamese characters with tone markers.

16. Accessibility (a11y)

• Aria-live regions for search result updates.
• Keyboard-accessible search dropdown results.

17. Observability & Analytics

• Tracking of "Top Search Terms" to understand content importance.
• Analytics on "Zero Result" searches to identify missing content.

18. Testing & Quality

• Integration tests for cross-tenant data leakage in search results.
• Performance testing with large datasets.

19. Constraints & Assumptions

• Assumes organization name indexing is sufficient for v1 discovery needs.

20. Future Enhancements

• MIME type filtering (e.g., Images only).
• Global cross-entity search across both files and folders.
• Full hierarchical path context in search results.
• Content search (OCR for PDFs and Images).
• Semantic search via the AI Assistant module integration.