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