# Library

This document describes the Library tab features including favorites, archive, trash, and other collections.

## Library Overview

The Library tab provides access to various collections and utility features:

```
┌─────────────────────────────────────────────────────────────┐
│                      Library Features                        │
├─────────────────────────────────────────────────────────────┤
│  Quick Access    │  Collections     │  Utilities            │
├──────────────────┼──────────────────┼───────────────────────┤
│  • Favorites     │  • People        │  • Folders            │
│  • Archive       │  • Places        │  • Locked Folder      │
│  • Shared Links  │  • Local Albums  │  • Partners           │
│  • Trash         │                  │                       │
└──────────────────┴──────────────────┴───────────────────────┘
```

## Favorites

### Purpose
- Quick access to favorite photos/videos
- Marked assets appear here
- Heart icon on assets

### Toggle Favorite API
```
PUT /assets

Body:
{
  "ids": ["asset-1", "asset-2"],
  "isFavorite": true
}
```

### UI Features
- Grid view of favorited assets
- Multi-select available
- Can unfavorite from here

## Archive

### Purpose
- Hide assets from main timeline
- Assets still searchable
- Good for screenshots, receipts, etc.

### Toggle Archive API
```
PUT /assets

Body:
{
  "ids": ["asset-1", "asset-2"],
  "isArchived": true
}
```

### Restore from Archive
Same API with `isArchived: false`

## Trash

### Purpose
- Deleted assets go here first
- Auto-deleted after 30 days (configurable)
- Can restore or permanently delete

### Trash Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Trash                                       [Empty All] │
├─────────────────────────────────────────────────────────────┤
│  Items in trash will be permanently deleted after 30 days   │
├─────────────────────────────────────────────────────────────┤
│  [Asset grid of trashed items]                              │
│                                                             │
│  Select to restore or delete permanently                    │
└─────────────────────────────────────────────────────────────┘
```

### Trash API Endpoints

**Move to Trash**
```
POST /trash/assets

Body:
{
  "ids": ["asset-1", "asset-2"]
}
```

**Restore from Trash**
```
POST /trash/restore/assets

Body:
{
  "ids": ["asset-1", "asset-2"]
}
```

**Restore All**
```
POST /trash/restore
```

**Empty Trash**
```
POST /trash/empty
```

## Shared Links

### Purpose
- Create public links to share assets/albums
- Password protection optional
- Expiration dates supported

### Shared Links Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Shared Links                              [+ Create]    │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │  📷 5 items                                          │   │
│  │  Created: Dec 15, 2024                               │   │
│  │  Expires: Never                                      │   │
│  │  🔗 Copy Link                           [Edit] [X]   │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  📁 Summer 2024 Album                                │   │
│  │  Created: Dec 10, 2024                               │   │
│  │  Expires: Dec 31, 2024  🔒 Password                  │   │
│  │  🔗 Copy Link                           [Edit] [X]   │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

### Shared Link Model
```
SharedLink {
  id: String
  description: String?
  slug: String?           // Custom URL slug
  password: String?       // If protected
  expiresAt: DateTime?    // Expiration
  allowDownload: Boolean  // Can download
  allowUpload: Boolean    // Can upload (albums)
  showMetadata: Boolean   // Show EXIF data
  type: LinkType          // ALBUM or INDIVIDUAL
  albumId: String?        // If album link
  assets: List<Asset>     // Linked assets
  createdAt: DateTime
}
```

### Shared Link API

**Create Link**
```
POST /shared-links

Body:
{
  "type": "ALBUM" | "INDIVIDUAL",
  "albumId": "album-uuid",        // for album links
  "assetIds": ["asset-1"],        // for individual links
  "description": "My photos",
  "password": "optional",
  "expiresAt": "2024-12-31T23:59:59Z",
  "allowDownload": true,
  "allowUpload": false,
  "showMetadata": true
}
```

**Update Link**
```
PATCH /shared-links/{id}

Body: (same fields as create)
```

**Delete Link**
```
DELETE /shared-links/{id}
```

## People Collection

### Purpose
- Browse photos by recognized faces
- Name and manage people
- Merge duplicate people

### People API
```
GET /people

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

### Person Detail Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  John Doe                                    [⋮]        │
├─────────────────────────────────────────────────────────────┤
│       [Large Face Thumbnail]                                │
│                                                             │
│       156 photos                                            │
├─────────────────────────────────────────────────────────────┤
│  [Grid of assets featuring this person]                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Update Person
```
PUT /people/{id}

Body:
{
  "name": "John Doe",
  "birthDate": "1990-01-15",
  "isHidden": false
}
```

## Places Collection

### Purpose
- Browse photos by location
- Map view of all geotagged photos
- Location clustering

### Places Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Places                                                  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │                                                      │   │
│  │              [Interactive Map]                       │   │
│  │              with asset markers                      │   │
│  │                                                      │   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│  [Grid of cities/places with thumbnails]                    │
│                                                             │
│  San Francisco    New York    Paris                         │
│  24 photos        56 photos   12 photos                     │
└─────────────────────────────────────────────────────────────┘
```

### Map Features
- Tap marker to see asset
- Cluster markers for dense areas
- Filter by date, favorites, partners
- Different map themes (light/dark)

## Local Albums (On This Device)

### Purpose
- Access device photo albums
- Select albums for backup
- View local-only content

### Local Album Features
- Shows all device photo albums
- Displays asset count
- Can browse contents
- Cannot modify from app (read-only)

## Folders

### Purpose
- Browse by server folder structure
- See how photos are organized on server
- Navigate folder hierarchy

### Folder API
```
GET /view/folder?path=/

Response:
{
  "folders": ["2024", "2023", "Screenshots"],
  "assets": [...]
}
```

## Locked Folder

### Purpose
- PIN-protected private folder
- Hidden from main views
- Biometric unlock option

### Locked Folder Flow
```
┌─────────────────────────────────────────────────────────────┐
│                    Locked Folder                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                       🔒                                    │
│                                                             │
│              Enter PIN to unlock                            │
│                                                             │
│              ┌───┬───┬───┬───┐                             │
│              │ ● │ ● │ ○ │ ○ │                             │
│              └───┴───┴───┴───┘                             │
│                                                             │
│              [Use Biometrics]                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Setup PIN
```
PUT /auth/pin-code

Body:
{
  "pinCode": "1234"
}
```

### Verify PIN
```
POST /auth/pin-code/verify

Body:
{
  "pinCode": "1234"
}
```

### Locked Assets
Assets can be moved to/from locked folder:
```
PUT /assets

Body:
{
  "ids": ["asset-1"],
  "visibility": "locked" | "timeline"
}
```

## Partners

### Purpose
- View photos shared by partners
- Include partner photos in timeline
- Manage partner relationships

### Partners Screen
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Partners                                                │
├─────────────────────────────────────────────────────────────┤
│  Sharing with you:                                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 Jane Doe                                          │   │
│  │     Include in timeline: [Toggle: ON]                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  You're sharing with:                                       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 John Smith                              [Remove]  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [+ Add Partner]                                            │
└─────────────────────────────────────────────────────────────┘
```

### Partner API

**Get Partners**
```
GET /partners?direction=shared-with|shared-by
```

**Add Partner**
```
POST /partners/{userId}
```

**Remove Partner**
```
DELETE /partners/{userId}
```

**Update Partner Settings**
```
PUT /partners/{userId}

Body:
{
  "inTimeline": true
}
```

---

[Previous: Albums](./albums.md) | [Next: Gallery Viewer](./gallery-viewer.md)