How aks-labs/cloudgallery works
1. What this repo is
- An Android-only photo backup and gallery app written in Kotlin with Jetpack Compose.
- The core architectural boundary is: device UI + local storage + Android media access + direct Telegram Bot API calls.
- There is no app-owned backend; the phone talks straight to Telegram.
2. User-facing presentation layer
- MainActivity hosts the Compose app shell.
- Navigation is split into app-level routes in ui/main/nav, with screens for:
- local gallery
- remote/Telegram gallery
- uploads management
- trash bin
- settings
- onboarding and permissions
- about/help
- ui/components contains most shared UI building blocks: photo grid/viewer, dialogs, bottom bars, empty states, scrollbars, selection, and FABs.
3. State management
- Each major screen has a dedicated ViewModel, such as LocalViewModel, RemoteViewModel, TrashViewModel, ManageUploadsViewModel, and PermissionViewModel.
- MainViewModel and SyncState coordinate app-wide state like connectivity, sync progress, and whether backup/download operations are active.
- This is a typical Compose state-driven UI: screens render from ViewModel state and trigger actions back into the sync/data layer.
4. Local photo source boundary
- The app reads the device’s photos through Android’s MediaStore, not by scanning files directly.
- data/mediastore holds the local-photo query and mapping layer:
- album/query helpers
- cursor extensions
- LocalUiPhoto and AlbumInfo
- This is the source of truth for what exists on the phone and what can be backed up.
5. Local persistence
- A Room database (WhDatabase) stores the app’s internal photo state.
- Key entities are:
- Photo — local photo records and sync metadata
- RemotePhoto — records for Telegram-side objects
- DeletedPhoto — tombstone/history for removed items
- DAOs provide the read/write boundary for gallery state, sync bookkeeping, and deleted-item tracking.
- There are multiple schema migrations, which indicates the database is a long-lived source of app state, not just a cache.
6. Preferences, key storage, and backup files
- Preferences and DbHolder manage app configuration and database access.
- The README states bot token and chat ID are protected with Android keystore/AES, while the synced-image metadata database can be exported/imported.
- data/localdb/backup plus workers for database export/backup show that the app treats its local metadata as a recoverable artifact, including restoration across devices.
- Important boundary: images are not stored in the local metadata DB; only IDs and metadata are.
7. Telegram integration layer
- api/BotApi, TelegramHttp, and TelegramRawApi implement direct communication with Telegram’s Bot API.
- This layer is responsible for upload, download, and remote metadata lookup against the user’s bot/chat.
- The app depends on Telegram as an external storage service, but not on a Telegram-specific SDK server; it uses direct HTTP/API calls.
8. Sync and background orchestration
- Most non-UI work is pushed into background jobs in workers/.
- Important jobs include:
- upload workers for new photos
- download workers for missing remote photos
- periodic sync/backup/export jobs
- remote-size reconciliation
- database/media-store synchronization
- CloudPhotoSyncService and HistoricalImageDiscoveryService suggest higher-level orchestration for initial discovery, backfill, and ongoing sync.
- This is the main data-processing pipeline of the app.
9. Primary data flows
- Backup flow: MediaStore photo on device → local app metadata → Telegram upload via Bot API → remote photo record stored locally.
- Restore/browse flow: Telegram remote metadata/media → local DB record → Compose gallery UI and image viewer.
- Metadata recovery flow: local DB export/import and Telegram-backed backup of the metadata state so a new device can reconstruct the gallery history.
- The architecture is therefore a bidirectional sync between phone storage and Telegram, with local DB acting as the reconciliation layer.
10. Image loading and remote rendering
- The app customizes Coil via utils/coil with a NetworkFetcher.
- That indicates Telegram-hosted media is loaded into the gallery through the app’s own image-loading path, not by static local files.
- This is important for the architecture diagram because the UI image pipeline is separate from the sync pipeline.
11. Android system integration
- The app relies on Android permissions, connectivity observation, notifications, and WorkManager-style background execution.
- utils/connectivity drives UI status and likely gates sync behavior when network changes.
- NotificationHelper suggests background sync progress and user-visible alerts are part of the system design.
12. Overall architectural shape
- Think of this repository as four layers:
- UI layer: Compose screens and reusable components
- State layer: ViewModels and sync state
- Domain/data layer: MediaStore, Room, preferences, backup, sync orchestration
- External boundary: Telegram Bot API plus Android system APIs
- The central design choice is that the app keeps its own metadata locally, while Telegram is the external vault for the actual photos.
Main entry points: AppNavHost.kt Nav host · WhDatabase.kt Room DB · workers Workers · RemotePhotoGrid.kt Remote gallery
Components 27
UI layer
Compose app shell, navigation, screens, and shared components.
- App · Application entry point and dependency setup.
app/src/main/java/com/akslabs/cloudgallery/App.kt - MainActivity · Hosts the app shell and root UI.
app/src/main/java/com/akslabs/cloudgallery/ui/MainActivity.kt - Nav host · App-level route graph and drawer navigation.
app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt - Main page · Main scaffold coordinating top-level app presentation.
app/src/main/java/com/akslabs/cloudgallery/ui/main/MainPage.kt - UI kit · Reusable photo grids, dialogs, bars, selection, and viewer widgets.
app/src/main/java/com/akslabs/cloudgallery/ui/components - Local gallery · Device photo browser and upload entry point.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalPhotoGrid.kt - Remote gallery · Telegram-backed gallery and download entry point.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt - Uploads · Manage pending and historical upload state.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsScreen.kt - Trash bin · Deleted-item browsing and recovery UI.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashBinScreen.kt - Settings · App settings and configuration surface.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/settings/SettingsScreen.kt - Onboarding · First-run guidance and permission request flow.
app/src/main/java/com/akslabs/cloudgallery/ui/onboarding
State layer
Screen ViewModels and app-wide sync state.
- Main VM · Coordinates connectivity, sync progress, and global app state.
app/src/main/java/com/akslabs/cloudgallery/ui/main/MainViewModel.kt - Local VM · Drives local gallery state and upload actions.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalViewModel.kt - Remote VM · Drives remote gallery state and download actions.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemoteViewModel.kt - Uploads VM · Manages upload queue and upload status views.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsViewModel.kt - Trash VM · Manages deleted-photo state and restore flows.
app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashViewModel.kt - Permission VM · Coordinates runtime permission prompts and results.
app/src/main/java/com/akslabs/cloudgallery/ui/permission/PermissionViewModel.kt - Sync state · Global sync status shared across screens.
app/src/main/java/com/akslabs/cloudgallery/ui/main/SyncState.kt
Data layer
Local MediaStore access, Room persistence, preferences, and backup artifacts.
- MediaStore · Queries and maps on-device photos and albums.
app/src/main/java/com/akslabs/cloudgallery/data/mediastore - Room DB · Persistent app state for photos, remote records, and tombstones.
app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt - Prefs · Stored settings and protected bot credentials.
app/src/main/java/com/akslabs/cloudgallery/data/localdb/Preferences.kt - DB backup · Local database backup and restore artifacts.
app/src/main/java/com/akslabs/cloudgallery/data/localdb/backup
Sync layer
Background workers and orchestration services for upload, download, reconciliation, and backup.
- Sync service · Higher-level coordination for cloud sync and discovery.
app/src/main/java/com/akslabs/cloudgallery/services/CloudPhotoSyncService.kt - Workers · Upload, download, backup, export, and reconciliation jobs.
app/src/main/java/com/akslabs/cloudgallery/workers
External boundary
Telegram Bot API and Android system services used by the app.
- Telegram API · Direct Bot API client for upload, download, and metadata lookup.
app/src/main/java/com/akslabs/cloudgallery/api - Image loader · Loads remote Telegram media into the UI image pipeline.
app/src/main/java/com/akslabs/cloudgallery/utils/coil - Android system · Permissions, connectivity, notifications, and background execution.
app/src/main/java/com/akslabs/cloudgallery/utils
Connections 33
- App → MainActivity: starts · Application launches the Compose host.
- MainActivity → Main page: hosts · Activity sets up the main app scaffold.
- Main page → Nav host: navigates · Scaffold delegates screen routing to navigation.
- Nav host → Local gallery: routes to · Provides local gallery entry.
- Nav host → Remote gallery: routes to · Provides remote gallery entry.
- Nav host → Uploads: routes to · Provides upload management entry.
- Nav host → Trash bin: routes to · Provides trash browsing entry.
- Nav host → Settings: routes to · Provides settings entry.
- Nav host → Onboarding: routes to · Provides onboarding and permission flow.
- Local gallery → Local VM: reads state · Renders device gallery from ViewModel state.
- Remote gallery → Remote VM: reads state · Renders Telegram gallery from ViewModel state.
- Uploads → Uploads VM: reads state · Renders upload management state.
- Trash bin → Trash VM: reads state · Renders deleted-item state.
- Onboarding → Permission VM: reads state · Permission flow is driven by ViewModel state.
- Main VM → Sync state: coordinates · Tracks global sync and connectivity status.
- Local VM → MediaStore: queries · Loads on-device albums and photos.
- Local VM → Workers: queues upload · Starts upload jobs for selected local photos.
- Remote VM → Telegram API: downloads · Fetches remote photo data from Telegram.
- Remote VM → Workers: queues download · Starts missing-photo download jobs.
- Uploads VM → Room DB: tracks · Reads and updates upload bookkeeping.
- Trash VM → Room DB: tracks · Uses tombstones and deletion history.
- Permission VM → Android system: requests · Handles runtime permission flow.
- MediaStore → Room DB: syncs into · Device photo inventory is reconciled into local metadata.
- Room DB → DB backup: exports/imports · Local metadata can be backed up and restored.
- Prefs → Room DB: configures · Controls database and app storage access.
- Workers → Telegram API: syncs · Upload, download, and metadata reconciliation jobs call Telegram.
- Workers → Sync service: orchestrates · Workers and services coordinate long-running sync flows.
- Sync service → MediaStore: discovers · Initial and ongoing photo discovery reads MediaStore.
- Sync service → Room DB: reconciles · Maintains local sync state and history.
- Telegram API → Image loader: feeds media · Remote media is rendered through custom image loading.
- Remote gallery → Image loader: renders with · Remote gallery displays Telegram-hosted images.
- Android system → Workers: schedules · Background execution and notifications support sync jobs.
- Android system → Main VM: observes · Connectivity state influences app-wide UI state.