add docs part 1
This commit is contained in:
422
docs/library.md
Normal file
422
docs/library.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user