# Search

This document describes the search functionality, including smart search, filters, and discovery features.

## Search Overview

The search feature allows users to find assets using:
- AI-powered semantic search (CLIP)
- Text-based search (filename, description, OCR)
- Filter-based search (people, location, camera, date, type)

## Search Screen Layout

```
┌─────────────────────────────────────────────────────────────┐
│  ←  [  Search photos and videos...        🔍 ]    [ ⋮ ]    │
├─────────────────────────────────────────────────────────────┤
│  [People] [Location] [Camera] [Date] [Type] [Display] →    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                    Search Results                           │
│                         or                                  │
│                    Empty State                              │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Search Types

### 1. Context Search (AI/CLIP)
- Default search mode
- Uses AI to understand image content
- Finds visually similar results

**Examples:**
- "sunset on the beach"
- "birthday cake"
- "dog playing in park"
- "red car"

### 2. Filename Search
- Searches asset filenames
- Partial matching supported

**Examples:**
- "IMG_2024"
- "screenshot"
- ".png"

### 3. Description Search
- Searches asset descriptions/captions
- User-added metadata

### 4. OCR Search
- Searches text detected in images
- Useful for documents, signs, receipts

**Examples:**
- "receipt"
- "invoice"
- Specific text in images

## Search API

### Main Search Endpoint
```
POST /search/smart

Body:
{
  "query": "sunset beach",
  "page": 1,
  "size": 100,
  "type": "IMAGE" | "VIDEO" | null,
  "isFavorite": true | false | null,
  "isArchived": true | false | null,
  "takenAfter": "2024-01-01T00:00:00Z",
  "takenBefore": "2024-12-31T23:59:59Z",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "make": "Apple",
  "model": "iPhone 15 Pro",
  "personIds": ["person-uuid-1", "person-uuid-2"],
  "language": "en-US"
}

Response:
{
  "assets": {
    "items": [...],
    "nextPage": "2"
  }
}
```

### Search Suggestions
```
GET /search/suggestions?type={type}&country={country}&state={state}&make={make}&model={model}

Types: country, state, city, cameraMake, cameraModel
```

## Filter Chips

### People Filter
```
┌─────────────────────────────────────────────────────────────┐
│  People                                                 X   │
├─────────────────────────────────────────────────────────────┤
│  Search people...                                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐              │
│  │ 👤  │  │ 👤  │  │ 👤  │  │ 👤  │  │ 👤  │              │
│  │     │  │     │  │     │  │     │  │     │              │
│  │John │  │Jane │  │Bob  │  │Alice│  │No   │              │
│  │  ✓  │  │     │  │     │  │  ✓  │  │Name │              │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘              │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘
```

### Location Filter
```
┌─────────────────────────────────────────────────────────────┐
│  Location                                               X   │
├─────────────────────────────────────────────────────────────┤
│  Country                                                    │
│  [Select country...                               ▼]       │
│                                                             │
│  State                                                      │
│  [Select state...                                 ▼]       │
│                                                             │
│  City                                                       │
│  [Select city...                                  ▼]       │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘
```

### Camera Filter
```
┌─────────────────────────────────────────────────────────────┐
│  Camera                                                 X   │
├─────────────────────────────────────────────────────────────┤
│  Make                                                       │
│  [Select camera make...                           ▼]       │
│                                                             │
│  Model                                                      │
│  [Select camera model...                          ▼]       │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘
```

### Date Filter
Uses native date range picker:
- Start date
- End date
- Presets: Today, This Week, This Month, This Year

### Media Type Filter
```
┌─────────────────────────────────────────────────────────────┐
│  Media Type                                             X   │
├─────────────────────────────────────────────────────────────┤
│  ○ All                                                      │
│  ○ Images only                                              │
│  ○ Videos only                                              │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘
```

### Display Options Filter
```
┌─────────────────────────────────────────────────────────────┐
│  Display Options                                        X   │
├─────────────────────────────────────────────────────────────┤
│  ☐ Not in any album                                         │
│  ☐ Archived only                                            │
│  ☐ Favorites only                                           │
│                                                             │
│  [Clear]                                    [Search]        │
└─────────────────────────────────────────────────────────────┘
```

## Search Filter Model

```
SearchFilter {
  // Text search
  context: String?      // AI search query
  filename: String?     // Filename search
  description: String?  // Description search
  ocr: String?          // OCR text search

  // Filters
  people: Set<Person>   // Selected people
  location: LocationFilter {
    country: String?
    state: String?
    city: String?
  }
  camera: CameraFilter {
    make: String?
    model: String?
  }
  date: DateFilter {
    takenAfter: DateTime?
    takenBefore: DateTime?
  }
  mediaType: AssetType  // image, video, or other (all)
  display: DisplayFilter {
    isNotInAlbum: Boolean
    isArchive: Boolean
    isFavorite: Boolean
  }
  rating: RatingFilter  // If rating feature enabled
  language: String      // For AI search localization
  assetId: String?      // Search for specific asset by ID
  tagIds: List<String>? // Filter by tag IDs
}
```

## Quick Links (Empty State)

When search is empty, show quick access links:

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│                      [Polaroid Image]                       │
│                                                             │
│               Search photos and videos                      │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │  🕐  Recently Taken                                  │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ▶️  Videos                                          │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  ♥️  Favorites                                       │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

## Explore Data

### Explore API
```
GET /search/explore

Response:
[
  {
    "fieldName": "exifInfo.city",
    "items": [
      {
        "value": "San Francisco",
        "data": { asset preview data }
      }
    ]
  },
  {
    "fieldName": "smartInfo.objects",
    "items": [...]
  }
]
```

## Places / Map View

### Get Assets by City
```
GET /search/cities

Response: Array of assets grouped by city
```

### Map Display
- Shows assets as markers on map
- Cluster markers for dense areas
- Tap cluster to zoom or view assets
- Filter by favorites, date range, partners

## People Search

### Get All People
```
GET /people

Response:
[
  {
    "id": "person-uuid",
    "name": "John Doe",
    "birthDate": "1990-01-15",
    "thumbnailPath": "/path/to/thumb",
    "isHidden": false
  }
]
```

### Person Detail
```
GET /people/{id}

Response:
{
  "id": "person-uuid",
  "name": "John Doe",
  "birthDate": "1990-01-15",
  "thumbnailPath": "/path/to/thumb",
  "assets": [...]
}
```

## Pagination

- Search results are paginated
- Initial page: 1
- Load more on scroll to bottom
- `nextPage` in response indicates more results

## Search Result Actions

Same as timeline multi-select:
- Add to album
- Favorite
- Archive
- Delete
- Share
- Download

## Performance Considerations

1. **Debounced input**: Wait for user to stop typing
2. **Cached suggestions**: Store frequently used
3. **Incremental loading**: Paginate results
4. **Cancel previous**: Cancel outdated requests

---

[Previous: Timeline & Photos](./timeline.md) | [Next: Albums](./albums.md)