# Albums

This document describes album creation, management, sharing, and related functionality.

## Album Overview

Albums are collections of assets that can be:
- **Personal**: Created by you, only visible to you
- **Shared**: Shared with other users who can view/contribute
- **Local**: Device albums (not synced to server)

## Album Model

```
Album {
  id: String              // Unique identifier
  name: String            // Album name
  description: String     // Album description
  ownerId: String         // Owner user ID
  ownerName: String       // Owner display name
  createdAt: DateTime     // Creation time
  updatedAt: DateTime     // Last modified
  thumbnailAssetId: String? // Cover image asset ID
  assetCount: Integer     // Number of assets
  isShared: Boolean       // Has shared users
  isActivityEnabled: Boolean // Comments/likes enabled
  order: AlbumAssetOrder  // asc or desc
  sharedUsers: List<User> // Users album is shared with
}
```

## Album List Screen

### Layout
```
┌─────────────────────────────────────────────────────────────┐
│  Albums                                     [List/Grid] ⚙️   │
├─────────────────────────────────────────────────────────────┤
│  [ 🔍 Search albums...                                  ]   │
├─────────────────────────────────────────────────────────────┤
│  Sort by: Recent Activity ▼               [+ Create Album]  │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │              │  │              │  │              │      │
│  │   [Cover]    │  │   [Cover]    │  │   [Cover]    │      │
│  │              │  │              │  │              │      │
│  │  Summer 2024 │  │  Family      │  │  Wedding     │      │
│  │  24 items    │  │  156 items   │  │  89 items    │      │
│  │  [👤 Shared] │  │              │  │  [👤👤 Shared]│      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

### Sort Options
| Option | Description |
|--------|-------------|
| Recent Activity | Most recently modified first |
| Album Name | Alphabetical order |
| Most Items | Largest albums first |
| Oldest First | By creation date ascending |

### Filter Modes
| Mode | Shows |
|------|-------|
| All | All albums |
| My Albums | Albums you own |
| Shared | Albums shared with you |
| Local | On-device albums |

## Album API Endpoints

### List Albums
```
GET /albums?shared=true|false|null

Response:
[
  {
    "id": "album-uuid",
    "albumName": "Summer 2024",
    "description": "Beach vacation photos",
    "ownerId": "user-uuid",
    "owner": { user object },
    "albumThumbnailAssetId": "asset-uuid",
    "assetCount": 24,
    "shared": true,
    "albumUsers": [...],
    "hasSharedLink": false,
    "isActivityEnabled": true,
    "order": "desc",
    "createdAt": "2024-06-15T10:00:00Z",
    "updatedAt": "2024-06-20T15:30:00Z"
  }
]
```

### Get Album Detail
```
GET /albums/{id}

Response: Full album object with assets
```

### Create Album
```
POST /albums

Body:
{
  "albumName": "New Album",
  "description": "Album description",
  "assetIds": ["asset-1", "asset-2"],
  "albumUsers": [
    { "userId": "user-uuid", "role": "editor" }
  ]
}

Response: Created album object
```

### Update Album
```
PATCH /albums/{id}

Body:
{
  "albumName": "Updated Name",
  "description": "New description",
  "isActivityEnabled": true,
  "order": "asc"
}
```

### Delete Album
```
DELETE /albums/{id}
```

## Album Detail Screen

### Layout
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Summer 2024                           [Select] [⋮]     │
├─────────────────────────────────────────────────────────────┤
│  Beach vacation with family                                 │
│  24 items • Shared with 3 people                           │
├─────────────────────────────────────────────────────────────┤
│  June 2024                                                  │
│  ┌─────┬─────┬─────┬─────┐                                 │
│  │     │     │     │     │                                 │
│  │ 📷  │ 📷  │ 🎥  │ 📷  │                                 │
│  │     │     │     │     │                                 │
│  └─────┴─────┴─────┴─────┘                                 │
│  ...                                                        │
├─────────────────────────────────────────────────────────────┤
│  [+ Add Photos]                              [💬 Activity]  │
└─────────────────────────────────────────────────────────────┘
```

### Album Actions Menu
| Action | Description |
|--------|-------------|
| Edit Album | Change name/description |
| Add Photos | Select assets to add |
| Share | Share with users or create link |
| Album Options | Advanced settings |
| Delete Album | Remove album (owner only) |
| Leave Album | Leave shared album |

## Album Creation Flow

### Step 1: Select Assets
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Add to Album                              [Create]      │
├─────────────────────────────────────────────────────────────┤
│  Selected: 5                                                │
├─────────────────────────────────────────────────────────────┤
│  [Asset selection grid - same as timeline]                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Step 2: Enter Details
```
┌─────────────────────────────────────────────────────────────┐
│  ←  Create Album                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Album Name                                                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Summer 2024                                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Description (optional)                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Beach vacation photos                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [Share with users] (optional)                              │
│                                                             │
│                                        [Create Album]       │
└─────────────────────────────────────────────────────────────┘
```

## Adding Assets to Album

### API Endpoint
```
PUT /albums/{id}/assets

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

Response:
{
  "successfullyAdded": 3,
  "alreadyInAlbum": ["asset-4"]
}
```

## Removing Assets from Album

### API Endpoint
```
DELETE /albums/{id}/assets

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

## Sharing Albums

### Share with Users
```
PUT /albums/{id}/users

Body:
{
  "albumUsers": [
    { "userId": "user-1", "role": "editor" },
    { "userId": "user-2", "role": "viewer" }
  ]
}
```

### User Roles
| Role | Can View | Can Add | Can Remove | Can Edit |
|------|----------|---------|------------|----------|
| viewer | ✓ | | | |
| editor | ✓ | ✓ | Own assets | |

### Remove User from Album
```
DELETE /albums/{id}/user/{userId}
```

### Leave Album (for shared users)
```
DELETE /albums/{id}/user/me
```

## Album Options Screen

```
┌─────────────────────────────────────────────────────────────┐
│  ←  Album Options                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Sort Order                                                 │
│  [Newest first ▼]                                          │
│                                                             │
│  ─────────────────────────────────────────────────────      │
│                                                             │
│  Allow Activity                             [Toggle: ON]    │
│  Enable comments and likes                                  │
│                                                             │
│  ─────────────────────────────────────────────────────      │
│                                                             │
│  Shared Users                                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 👤 John Doe (Editor)                           [X]  │   │
│  │ 👤 Jane Smith (Viewer)                         [X]  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [+ Add Users]                                              │
│                                                             │
│  ─────────────────────────────────────────────────────      │
│                                                             │
│  [Delete Album]  (red, destructive)                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Local Albums

### Device Albums
- Albums from device photo gallery
- Read-only in the app
- Can be selected for backup
- Synced to server when enabled

### Local Album Model
```
LocalAlbum {
  id: String           // Device album ID
  name: String         // Album name
  assetCount: Integer  // Number of assets
  modifiedAt: DateTime // Last modified
  isAll: Boolean       // Is "All Photos" album
  thumbnailId: String? // Cover asset ID
}
```

## Album Sync

### Sync Album Feature
When enabled, uploaded assets are automatically added to matching remote albums:

1. Asset uploaded with album names in metadata
2. Server checks for existing albums with those names
3. Creates albums if they don't exist
4. Adds asset to matching albums

### API for Album Sync
```
POST /albums/{albumName}/assets

Body:
{
  "assetIds": ["asset-1"]
}
```

## Album Search

### Local Search
- Filter album list by name
- Instant results as you type

### Quick Filter Chips
| Filter | Shows |
|--------|-------|
| All | All albums |
| Mine | Albums you created |
| Shared | Albums shared with you |

---

[Previous: Search](./search.md) | [Next: Library](./library.md)