immish/docs/albums.md

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 | Next: Library