# aks-labs/cloudgallery architecture

> Architecture diagram of the GitHub repository aks-labs/cloudgallery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aks-labs/cloudgallery
- Repository: https://github.com/aks-labs/cloudgallery

## Overview

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: [`app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt`](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt) (Nav host), [`app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt`](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt) (Room DB), [`app/src/main/java/com/akslabs/cloudgallery/workers`](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/workers) (Workers), [`app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt`](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt) (Remote gallery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI layer"]
  node_app["App<br/>[App.kt]"]
  node_main_activity["MainActivity<br/>Compose host<br/>[MainActivity.kt]"]
  node_nav_host["Nav host<br/>navigation<br/>[AppNavHost.kt]"]
  node_main_page["Main page<br/>shell UI<br/>[MainPage.kt]"]
  node_shared_components["UI kit<br/>Compose components"]
  node_local_screen["Local gallery<br/>screen<br/>[LocalPhotoGrid.kt]"]
  node_remote_screen["Remote gallery<br/>screen<br/>[RemotePhotoGrid.kt]"]
  node_uploads_screen["Uploads<br/>screen"]
  node_trash_screen["Trash bin<br/>screen<br/>[TrashBinScreen.kt]"]
  node_settings_screen["Settings<br/>screen<br/>[SettingsScreen.kt]"]
  node_onboarding_permission["Onboarding<br/>screen flow"]
end

subgraph group_state["State layer"]
  node_main_vm["Main VM<br/>state coordinator<br/>[MainViewModel.kt]"]
  node_local_vm["Local VM<br/>screen state<br/>[LocalViewModel.kt]"]
  node_remote_vm["Remote VM<br/>screen state<br/>[RemoteViewModel.kt]"]
  node_uploads_vm["Uploads VM<br/>screen state"]
  node_trash_vm["Trash VM<br/>screen state<br/>[TrashViewModel.kt]"]
  node_permission_vm["Permission VM<br/>screen state"]
  node_sync_state(("Sync state<br/>shared state<br/>[SyncState.kt]"))
end

subgraph group_data["Data layer"]
  node_mediastore[("MediaStore<br/>device photo source")]
  node_wh_db[("Room DB<br/>local metadata DB<br/>[WhDatabase.kt]")]
  node_preferences["Prefs<br/>secure config<br/>[Preferences.kt]"]
  node_backup_files["DB backup<br/>export/import"]
end

subgraph group_sync["Sync layer"]
  node_sync_service["Sync service<br/>orchestration service"]
  node_workers["Workers<br/>background jobs"]
end

subgraph group_external["External boundary"]
  node_telegram_api["Telegram API<br/>HTTP integration"]
  node_image_loader["Image loader<br/>Coil fetcher"]
  node_android_system["Android system<br/>platform APIs"]
end

node_app -->|"starts"| node_main_activity
node_main_activity -->|"hosts"| node_main_page
node_main_page -->|"navigates"| node_nav_host
node_nav_host -->|"routes to"| node_local_screen
node_nav_host -->|"routes to"| node_remote_screen
node_nav_host -->|"routes to"| node_uploads_screen
node_nav_host -->|"routes to"| node_trash_screen
node_nav_host -->|"routes to"| node_settings_screen
node_nav_host -->|"routes to"| node_onboarding_permission
node_local_screen -->|"reads state"| node_local_vm
node_remote_screen -->|"reads state"| node_remote_vm
node_uploads_screen -->|"reads state"| node_uploads_vm
node_trash_screen -->|"reads state"| node_trash_vm
node_onboarding_permission -->|"reads state"| node_permission_vm
node_main_vm -->|"coordinates"| node_sync_state
node_local_vm -->|"queries"| node_mediastore
node_local_vm -->|"queues upload"| node_workers
node_remote_vm -->|"downloads"| node_telegram_api
node_remote_vm -->|"queues download"| node_workers
node_uploads_vm -->|"tracks"| node_wh_db
node_trash_vm -->|"tracks"| node_wh_db
node_permission_vm -->|"requests"| node_android_system
node_mediastore -->|"syncs into"| node_wh_db
node_wh_db -->|"exports/imports"| node_backup_files
node_preferences -->|"configures"| node_wh_db
node_workers -->|"syncs"| node_telegram_api
node_workers -->|"orchestrates"| node_sync_service
node_sync_service -->|"discovers"| node_mediastore
node_sync_service -->|"reconciles"| node_wh_db
node_telegram_api -->|"feeds media"| node_image_loader
node_remote_screen -->|"renders with"| node_image_loader
node_android_system -->|"schedules"| node_workers
node_android_system -->|"observes"| node_main_vm

click node_app "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/App.kt"
click node_main_activity "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/MainActivity.kt"
click node_nav_host "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt"
click node_main_page "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/MainPage.kt"
click node_shared_components "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/ui/components"
click node_local_screen "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalPhotoGrid.kt"
click node_remote_screen "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt"
click node_uploads_screen "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsScreen.kt"
click node_trash_screen "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashBinScreen.kt"
click node_settings_screen "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/settings/SettingsScreen.kt"
click node_onboarding_permission "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/ui/onboarding"
click node_main_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/MainViewModel.kt"
click node_local_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalViewModel.kt"
click node_remote_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemoteViewModel.kt"
click node_uploads_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsViewModel.kt"
click node_trash_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashViewModel.kt"
click node_permission_vm "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/permission/PermissionViewModel.kt"
click node_sync_state "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/SyncState.kt"
click node_mediastore "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/data/mediastore"
click node_wh_db "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt"
click node_preferences "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/Preferences.kt"
click node_backup_files "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/backup"
click node_telegram_api "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/api"
click node_sync_service "https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/services/CloudPhotoSyncService.kt"
click node_workers "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/workers"
click node_image_loader "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/utils/coil"
click node_android_system "https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/utils"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_main_activity,node_nav_host,node_main_page,node_shared_components,node_local_screen,node_remote_screen,node_uploads_screen,node_trash_screen,node_settings_screen,node_onboarding_permission toneBlue
class node_main_vm,node_local_vm,node_remote_vm,node_uploads_vm,node_trash_vm,node_permission_vm,node_sync_state toneAmber
class node_mediastore,node_wh_db,node_preferences,node_backup_files toneMint
class node_sync_service,node_workers toneRose
class node_telegram_api,node_image_loader,node_android_system toneIndigo
```

## Components

### UI layer

Compose app shell, navigation, screens, and shared components.

- [App](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/App.kt): Android app · Application entry point and dependency setup. · `app/src/main/java/com/akslabs/cloudgallery/App.kt`
- [MainActivity](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/MainActivity.kt): Compose host · Hosts the app shell and root UI. · `app/src/main/java/com/akslabs/cloudgallery/ui/MainActivity.kt`
- [Nav host](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt): navigation · App-level route graph and drawer navigation. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/nav/AppNavHost.kt`
- [Main page](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/MainPage.kt): shell UI · Main scaffold coordinating top-level app presentation. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/MainPage.kt`
- [UI kit](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/ui/components): Compose components · Reusable photo grids, dialogs, bars, selection, and viewer widgets. · `app/src/main/java/com/akslabs/cloudgallery/ui/components`
- [Local gallery](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalPhotoGrid.kt): screen · Device photo browser and upload entry point. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalPhotoGrid.kt`
- [Remote gallery](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt): screen · Telegram-backed gallery and download entry point. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemotePhotoGrid.kt`
- [Uploads](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsScreen.kt): screen · Manage pending and historical upload state. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsScreen.kt`
- [Trash bin](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashBinScreen.kt): screen · Deleted-item browsing and recovery UI. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashBinScreen.kt`
- [Settings](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/settings/SettingsScreen.kt): screen · App settings and configuration surface. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/settings/SettingsScreen.kt`
- [Onboarding](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/ui/onboarding): screen flow · 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](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/MainViewModel.kt): state coordinator · Coordinates connectivity, sync progress, and global app state. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/MainViewModel.kt`
- [Local VM](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalViewModel.kt): screen state · Drives local gallery state and upload actions. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/local/LocalViewModel.kt`
- [Remote VM](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemoteViewModel.kt): screen state · Drives remote gallery state and download actions. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/remote/RemoteViewModel.kt`
- [Uploads VM](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsViewModel.kt): screen state · Manages upload queue and upload status views. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/uploads/ManageUploadsViewModel.kt`
- [Trash VM](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashViewModel.kt): screen state · Manages deleted-photo state and restore flows. · `app/src/main/java/com/akslabs/cloudgallery/ui/main/screens/trash/TrashViewModel.kt`
- [Permission VM](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/permission/PermissionViewModel.kt): screen state · Coordinates runtime permission prompts and results. · `app/src/main/java/com/akslabs/cloudgallery/ui/permission/PermissionViewModel.kt`
- [Sync state](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/ui/main/SyncState.kt): shared 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](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/data/mediastore): device photo source · Queries and maps on-device photos and albums. · `app/src/main/java/com/akslabs/cloudgallery/data/mediastore`
- [Room DB](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt): local metadata DB · Persistent app state for photos, remote records, and tombstones. · `app/src/main/java/com/akslabs/cloudgallery/data/localdb/WhDatabase.kt`
- [Prefs](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/Preferences.kt): secure config · Stored settings and protected bot credentials. · `app/src/main/java/com/akslabs/cloudgallery/data/localdb/Preferences.kt`
- [DB backup](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/data/localdb/backup): export/import · 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](https://github.com/aks-labs/cloudgallery/blob/main/app/src/main/java/com/akslabs/cloudgallery/services/CloudPhotoSyncService.kt): orchestration service · Higher-level coordination for cloud sync and discovery. · `app/src/main/java/com/akslabs/cloudgallery/services/CloudPhotoSyncService.kt`
- [Workers](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/workers): background jobs · 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](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/api): HTTP integration · Direct Bot API client for upload, download, and metadata lookup. · `app/src/main/java/com/akslabs/cloudgallery/api`
- [Image loader](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/utils/coil): Coil fetcher · Loads remote Telegram media into the UI image pipeline. · `app/src/main/java/com/akslabs/cloudgallery/utils/coil`
- [Android system](https://github.com/aks-labs/cloudgallery/tree/main/app/src/main/java/com/akslabs/cloudgallery/utils): platform APIs · Permissions, connectivity, notifications, and background execution. · `app/src/main/java/com/akslabs/cloudgallery/utils`

## Connections

- 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.
