# Data Models

Core data structures used throughout the application.

## Asset

The fundamental unit representing a photo or video.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | Integer | Local database ID (auto-increment) |
| remoteId | String? | Server-side UUID |
| localId | String? | Device media library ID |
| checksum | String | SHA1 hash (base64 encoded) |
| thumbhash | String? | Compact image placeholder hash |
| ownerId | Integer | Hash of owner's user ID |
| fileCreatedAt | DateTime | When file was originally created |
| fileModifiedAt | DateTime | When file was last modified |
| updatedAt | DateTime | Last server update timestamp |
| durationInSeconds | Integer | Video duration (0 for images) |
| type | AssetType | image, video, audio, or other |
| width | Integer? | Image/video width in pixels |
| height | Integer? | Image/video height in pixels |
| fileName | String | Original filename |
| livePhotoVideoId | String? | ID of video component for live photos |
| isFavorite | Boolean | Marked as favorite |
| isArchived | Boolean | Hidden from main timeline |
| isTrashed | Boolean | In trash (pending deletion) |
| isOffline | Boolean | Server asset not accessible |
| stackId | String? | ID of stack this asset belongs to |
| stackPrimaryAssetId | String? | Primary asset in the stack |
| stackCount | Integer | Number of assets in stack |
| visibility | Enum | timeline, archive, hidden, locked |

### Asset Types

```
AssetType:
- other: Unknown file type
- image: Photo (JPEG, PNG, HEIC, etc.)
- video: Video file (MP4, MOV, etc.)
- audio: Audio file
```

### Asset State

Describes where asset data comes from:

```
AssetState:
- local: Only exists on device
- remote: Only exists on server
- merged: Exists on both (synced)
```

### Asset Visibility

```
AssetVisibilityEnum:
- timeline: Visible in main timeline
- archive: In archive (hidden from timeline)
- hidden: Hidden (private)
- locked: In locked folder (PIN protected)
```

### Computed Properties

| Property | Description |
|----------|-------------|
| isLocal | Has local device ID |
| isRemote | Has server ID |
| isImage | Type is image |
| isVideo | Type is video |
| isMotionPhoto | Has live photo video component |
| aspectRatio | Width / height ratio |
| duration | Duration as time object |
| name | Filename without extension |
| storage | Current asset state |
| isFlipped | EXIF indicates rotation 90/270 |
| orientatedWidth | Width accounting for rotation |
| orientatedHeight | Height accounting for rotation |

## Album

Collection of assets.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | Integer | Local database ID |
| remoteId | String? | Server-side UUID |
| name | String | Album name |
| createdAt | DateTime | Creation timestamp |
| modifiedAt | DateTime | Last modification |
| startDate | DateTime? | Earliest asset date |
| endDate | DateTime? | Latest asset date |
| lastModifiedAssetTimestamp | DateTime? | When assets last changed |
| shared | Boolean | Is shared with others |
| ownerId | Integer | Owner's user ID hash |
| owner | User | Owner user object |
| activityEnabled | Boolean | Comments/likes allowed |
| isRemote | Boolean | Exists on server |
| assetCount | Integer | Number of assets |

### Album Types

- **Regular Album**: User-created collection
- **Shared Album**: Shared with other users
- **Partner Album**: Virtual album showing partner's assets

## User

Represents an app user.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | String | Unique user UUID |
| email | String | User's email address |
| name | String | Display name |
| profileImagePath | String? | URL to profile picture |
| isAdmin | Boolean | Has admin privileges |
| memoryEnabled | Boolean | Show memories feature |
| avatarColor | Color | Generated avatar color |
| quotaUsageInBytes | Integer | Storage used |
| quotaSizeInBytes | Integer? | Storage quota (null = unlimited) |
| inTimeline | Boolean | Show in partner timeline |
| isPartnerSharedBy | Boolean | Sharing with current user |
| isPartnerSharedWith | Boolean | Current user shares with them |

## ExifInfo

Metadata extracted from images.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| assetId | Integer | Associated asset ID |
| make | String? | Camera manufacturer |
| model | String? | Camera model |
| lens | String? | Lens used |
| fNumber | Float? | Aperture f-stop |
| focalLength | Float? | Focal length in mm |
| iso | Integer? | ISO sensitivity |
| exposureTime | String? | Shutter speed |
| latitude | Float? | GPS latitude |
| longitude | Float? | GPS longitude |
| city | String? | Location city |
| state | String? | Location state/province |
| country | String? | Location country |
| description | String? | Image description/caption |
| dateTimeOriginal | DateTime? | Original capture time |

### Computed Properties

| Property | Description |
|----------|-------------|
| hasCoordinates | Has valid GPS data |
| isFlipped | Orientation is 90 or 270 degrees |

## Activity

Comment or like on shared album.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | String | Activity UUID |
| assetId | String? | Specific asset (null = album-level) |
| comment | String? | Comment text (null for likes) |
| createdAt | DateTime | When activity was created |
| type | ActivityType | comment or like |
| user | User | User who created activity |

### Activity Types

```
ActivityType:
- comment: Text comment
- like: Thumbs up reaction
```

## Search Filters

Parameters for searching assets.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| context | String? | Text to search |
| filename | String? | Search by filename |
| personIds | List<String> | Filter by people |
| location | SearchLocationFilter? | City/state/country |
| camera | SearchCameraFilter? | Make/model |
| date | SearchDateFilter? | Date range |
| display | SearchDisplayFilters? | Archive/favorite/trash |
| mediaType | AssetType? | Image/video filter |

### Location Filter

```
SearchLocationFilter:
- city: String?
- state: String?
- country: String?
```

### Camera Filter

```
SearchCameraFilter:
- make: String?
- model: String?
```

### Date Filter

```
SearchDateFilter:
- takenAfter: DateTime?
- takenBefore: DateTime?
```

### Display Filters

```
SearchDisplayFilters:
- isArchived: Boolean?
- isFavorite: Boolean?
- isNotInAlbum: Boolean?
```

## Memory

"On this day" memories feature.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | String | Memory UUID |
| title | String | Display title |
| assets | List<Asset> | Assets in this memory |
| yearsAgo | Integer | How many years ago |

## Backup Album

Local album selected for backup.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| id | String | Device album ID |
| name | String | Album name |
| selection | BackupSelection | include, exclude, or none |
| lastBackup | DateTime? | Last successful backup time |

## Store Keys

Key-value storage for app state and settings.

### Key Categories

**Authentication:**
- serverUrl, serverEndpoint
- accessToken
- currentUser

**Backup:**
- autoBackup, backgroundBackup
- backupRequireWifi, backupRequireCharging
- backupTriggerDelay
- backupFailedSince

**Display:**
- themeMode, primaryColor
- dynamicTheme, colorfulInterface
- tilesPerRow, dynamicLayout
- groupAssetsBy

**Cache:**
- thumbnailCacheSize
- imageCacheSize
- albumThumbnailCacheSize

**Features:**
- syncAlbums
- betaTimeline
- enableHapticFeedback

**Map:**
- mapThemeMode
- mapShowFavoriteOnly
- mapIncludeArchived
- mapwithPartners
- mapRelativeDate

---

[Previous: WebSocket](websocket.md) | [Next: API Reference](api-reference.md)