add docs part 1
This commit is contained in:
262
docs/main-screens.md
Normal file
262
docs/main-screens.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Main Navigation
|
||||
|
||||
This document describes the main app navigation structure and the primary screens.
|
||||
|
||||
## Tab Navigation
|
||||
|
||||
The app uses a bottom tab bar with 4 main sections:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ Current Tab Content │
|
||||
│ │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Photos │ Search │ Albums │ Library │
|
||||
│ 📷 │ 🔍 │ 📁 │ 📚 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Tab Indices
|
||||
| Index | Tab | Description |
|
||||
|-------|-----|-------------|
|
||||
| 0 | Photos | Main timeline view |
|
||||
| 1 | Search | Smart search and explore |
|
||||
| 2 | Albums | Album management |
|
||||
| 3 | Library | Collections and utilities |
|
||||
|
||||
## Photos Tab (Timeline)
|
||||
|
||||
The primary view showing all photos and videos chronologically.
|
||||
|
||||
### Screen Layout
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ App Bar [Avatar] ⚙️ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌───────────────────────────────────────────────────────┐ │
|
||||
│ │ Memory Lane (Horizontal Scroll) │ │
|
||||
│ │ [1 Year] [2 Years] [3 Years] [4 Years] │ │
|
||||
│ └───────────────────────────────────────────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ December 2024 │
|
||||
│ ┌─────┬─────┬─────┬─────┐ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ 📷 │ 📷 │ 🎥 │ 📷 │ │
|
||||
│ │ │ │ │ │ │
|
||||
│ ├─────┼─────┼─────┼─────┤ │
|
||||
│ │ │ │ │ │ │
|
||||
│ │ 📷 │ 📷 │ 📷 │ 🎥 │ │
|
||||
│ │ │ │ │ │ │
|
||||
│ └─────┴─────┴─────┴─────┘ │
|
||||
│ November 2024 │
|
||||
│ ... │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Features
|
||||
- **Memory Lane**: Shows photos from years past
|
||||
- **Grouped by date**: Sections for each month/day
|
||||
- **Pull to refresh**: Sync with server
|
||||
- **Multi-select**: Long press to select multiple assets
|
||||
- **Scroll scrubber**: Quick navigation by date
|
||||
|
||||
### App Bar Components
|
||||
- **User avatar**: Tap to access user menu
|
||||
- **Settings icon**: Navigate to settings
|
||||
- **Shows backup status**: Indicator when backup active
|
||||
|
||||
### Memory Lane
|
||||
- Horizontal scrollable cards
|
||||
- Each card represents photos from X years ago
|
||||
- Tapping opens memory viewer
|
||||
- Only shows if user has memories enabled
|
||||
|
||||
## Search Tab
|
||||
|
||||
Smart search with filters and discovery features.
|
||||
|
||||
### Screen Layout
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ← Back [ Search photos and videos... ] [Menu] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ [People] [Location] [Camera] [Date] [Type] [Display] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Search Results Grid │
|
||||
│ OR │
|
||||
│ Empty State with │
|
||||
│ Quick Links: │
|
||||
│ - Recently Taken │
|
||||
│ - Videos │
|
||||
│ - Favorites │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Search Types
|
||||
| Type | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| Context | AI-powered semantic search | "sunset on beach" |
|
||||
| Filename | Search by filename | "IMG_2024" |
|
||||
| Description | Search asset descriptions | "birthday party" |
|
||||
| OCR | Search text in images | "receipt" |
|
||||
|
||||
### Filter Chips
|
||||
- **People**: Filter by recognized faces
|
||||
- **Location**: Filter by country/state/city
|
||||
- **Camera**: Filter by camera make/model
|
||||
- **Date**: Date range picker
|
||||
- **Media Type**: Images, Videos, or All
|
||||
- **Display Options**: Favorites, Archived, Not in Album
|
||||
|
||||
## Albums Tab
|
||||
|
||||
View and manage albums.
|
||||
|
||||
### Screen Layout
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Albums [Grid] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ [Search albums...] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Sort: Recent ▼ [+ Create Album] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ [Thumb] │ │ [Thumb] │ │ [Thumb] │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ Album 1 │ │ Album 2 │ │ Album 3 │ │
|
||||
│ │ 24 items │ │ 12 items │ │ 8 items │ │
|
||||
│ │ [Shared] │ │ │ │ │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ │ │ │ │
|
||||
│ │ [Thumb] │ │ [Thumb] │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ Album 4 │ │ Album 5 │ │
|
||||
│ │ 156 items │ │ 3 items │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Album Types
|
||||
- **My Albums**: Albums you created
|
||||
- **Shared Albums**: Albums shared with you
|
||||
- **Local Albums**: Albums on device (not synced)
|
||||
|
||||
### Sort Options
|
||||
- Recently Activity
|
||||
- Album Name
|
||||
- Most Items
|
||||
- Last Modified
|
||||
|
||||
### Album Card Shows
|
||||
- Thumbnail image
|
||||
- Album name
|
||||
- Item count
|
||||
- Shared indicator (if applicable)
|
||||
- Owner avatar (if shared)
|
||||
|
||||
## Library Tab
|
||||
|
||||
Collection of features and utilities.
|
||||
|
||||
### Screen Layout
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ App Bar │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||||
│ │ ♥ Favorites │ │ 📦 Archive │ │
|
||||
│ └─────────────────────┘ └─────────────────────┘ │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
||||
│ │ 🔗 Shared Links │ │ 🗑 Trash │ │
|
||||
│ └─────────────────────┘ └─────────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ [People Grid] [Places Map] │ │
|
||||
│ │ 4 face thumbnails Map preview │ │
|
||||
│ │ │ │
|
||||
│ │ People Places │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ [Local Albums Grid] │ │
|
||||
│ │ 4 album thumbnails │ │
|
||||
│ │ │ │
|
||||
│ │ On This Device │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌────────────────────────────────────────────────────────┐ │
|
||||
│ │ 📁 Folders │ │
|
||||
│ │ 🔒 Locked Folder │ │
|
||||
│ │ 👥 Partners │ │
|
||||
│ │ └─ Partner 1's photos │ │
|
||||
│ │ └─ Partner 2's photos │ │
|
||||
│ └────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Quick Access Buttons
|
||||
| Button | Description |
|
||||
|--------|-------------|
|
||||
| Favorites | View all favorited assets |
|
||||
| Archive | View archived assets (hidden from timeline) |
|
||||
| Shared Links | Manage public sharing links |
|
||||
| Trash | View deleted items (before permanent deletion) |
|
||||
|
||||
### Collection Cards
|
||||
- **People**: Face recognition results, shows top 4 faces
|
||||
- **Places**: Map thumbnail, opens map view
|
||||
- **On This Device**: Local albums on device
|
||||
|
||||
### Additional Features
|
||||
- **Folders**: Browse by folder structure
|
||||
- **Locked Folder**: PIN-protected private photos
|
||||
- **Partners**: View photos shared by partners
|
||||
|
||||
## Navigation Guards
|
||||
|
||||
Routes are protected by guards that check:
|
||||
|
||||
| Guard | Purpose |
|
||||
|-------|---------|
|
||||
| AuthGuard | Requires valid authentication |
|
||||
| DuplicateGuard | Prevents duplicate route pushes |
|
||||
| BackupPermissionGuard | Requires gallery permission for backup |
|
||||
| GalleryGuard | Checks gallery access |
|
||||
| LockedGuard | Requires PIN for locked folder |
|
||||
|
||||
## Deep Linking
|
||||
|
||||
The app supports deep links for:
|
||||
- `immich://` scheme for OAuth callbacks
|
||||
- `my.immich.app` host for web-to-app links
|
||||
- Specific routes like shared albums, memories
|
||||
|
||||
### Deep Link Examples
|
||||
```
|
||||
immich://oauth-callback?code=xxx&state=yyy
|
||||
https://my.immich.app/share/xxx
|
||||
https://my.immich.app/albums/xxx
|
||||
```
|
||||
|
||||
## App Lifecycle
|
||||
|
||||
The app responds to lifecycle events:
|
||||
|
||||
| State | Action |
|
||||
|-------|--------|
|
||||
| Resumed | Refresh data, reconnect WebSocket |
|
||||
| Inactive | Pause non-essential operations |
|
||||
| Paused | Save state, disconnect WebSocket |
|
||||
| Detached | Clean up resources |
|
||||
| Hidden | Similar to paused |
|
||||
|
||||
---
|
||||
|
||||
[Previous: Authentication & Login](./login-flow.md) | [Next: Timeline & Photos](./timeline.md)
|
||||
Reference in New Issue
Block a user