ds-galo/android

galo Android client

Native Android client for a self-hosted galo instance: browse albums and media, watch photos/videos/360 panoramas, follow live album updates, and upload from the device with a persistent background queue and offline cache.

Kotlin + Jetpack Compose, minSdk 28, targetSdk 35. The module is standalone: it does not touch backend/ or frontend/, and consumes the existing HTTP API without server changes.

Requirements

• JDK 17
• Android SDK (platforms;android-35, build-tools;35.0.0, platform-tools)
• ANDROID_HOME pointing at the SDK, or android/local.properties with sdk.dir=<path>

Build

cd android
./gradlew :app:assembleDebug        # debug APK
./gradlew test                      # JVM unit + Robolectric UI tests
./gradlew lintDebug                 # Android lint
./gradlew :app:assembleRelease      # unsigned release APK without a keystore

From the repository root:

make android                        # runs :app:assembleDebug (ANDROID_SDK=... to override)
make install-android-app            # build and install the debug APK on a device

install-android-app builds the debug APK and installs it onto the sole connected device. To choose a device explicitly, pass its serial number:

make install-android-app SERIAL=emulator-5554

SERIAL also falls back to $ANDROID_SERIAL. When several devices are connected and SERIAL is not set, the target prints the list of devices (only those in the device state) and stops without installing. ADB=... overrides the adb binary (defaults to $(ANDROID_SDK)/platform-tools/adb).

Debug output: android/app/build/outputs/apk/debug/app-debug.apk.

Signing (release)

The release keystore and credentials live outside the repository. Point the build at a properties file with GALO_KEYSTORE_PROPERTIES=/path/keystore.properties, or place an ignored android/keystore.properties:

storeFile=/secure/galo-release.jks
storePassword=...
keyAlias=galo
keyPassword=...

Without it, assembleRelease still resolves and produces an unsigned APK; no secrets are stored in the repository.

First run

1. Enter the instance base URL (e.g. https://photos.example.com) and confirm — the app checks GET /api/health.
2. Plain http:// is blocked by default. For a trusted LAN instance, enable Небезопасное соединение (только LAN); the UI then marks the connection as insecure. The manifest permits cleartext, but the client itself refuses HTTP until you opt in.
3. Log in or register. Tokens are stored in the platform Keystore (EncryptedSharedPreferences) and refreshed transparently on 401.

Upload notes

• Uses the system Photo Picker; pick files, then choose the destination album.
• One file per multipart POST (the server's batch upload is fail-fast and caps the total body size), so each file gets its own status and retry.
• Queue is persisted in Room and resumes after an app/device restart. Large and video uploads show a foreground progress notification; transient failures retry with exponential backoff (up to 3 attempts).
• Optional Только Wi-Fi limits uploads to unmetered networks; jobs wait in the queue until Wi-Fi is available.
• HEIC/HEIF originals are converted to JPEG on-device (the server decodes only JPEG/PNG/GIF/BMP/TIFF). Capture date and geolocation are carried over via EXIF and the base filename is preserved. Note: for HEIC sources the stored "original" is the converted JPEG.

Offline cache

Album metadata and photo pages are cached in Room; media is cached by Coil keyed by the object path without the signed query, so the cache is reused when the signature rotates. Albums and photo grids open from cache when offline.

Live updates

While the app is signed in the client holds the personal stream GET /api/sse/me (authorized by the bearer header, not a query token) and applies album lifecycle events (album.created, album.updated, album.deleted) straight to the local cache, so the album list and an open album screen follow changes made elsewhere without a manual refresh. After a reconnect the list is re-synced over REST, which also drops albums deleted while the stream was down. When an album is deleted or the user is removed from it, the album leaves the list and the open album screen returns to it.

While an album screen is active the client also holds GET /api/sse/albums/:id and backfills missed photo changes via GET /api/albums/:id/photos?since= after a reconnect.

The streaming client does not refresh tokens by itself: it is built without the authenticator that ordinary API calls use, and the authorization interceptor only reads the current access token. A reconnect after expiry therefore restarts with whatever token is stored, and recovers once any other request has refreshed it; a client that idles with only the stream open keeps retrying with the stale token until the next API call renews it.

Attributes and actions

The mobile client mirrors the web workspace's attribute/action management.

• Album panel. Swiping right-to-left on any album screen (server or device) opens the «Атрибуты и действия» panel with the sections «Обложка», «Информация», «Навигация» and «Действия» (rename, delete). Cover and navigation are limited to owner/admin. For a device album linked to a server album, the panel shows the linked server album's real attributes; an unlinked device album shows local values (cover, name, item count) without the navigation section.
• Photo sheet. Swiping up in full-screen viewing (server or device) opens the «Атрибуты и действия» sheet with «Информация», «Метки» and «Действия» (download, move, copy, set as cover, delete) plus rename by tapping the file name. The sheet does not open while an image is zoomed, a panorama rotates, or video controls are in use. For device media linked to a server photo, the sheet shows that photo's server attributes and actions; otherwise it shows local properties.
• Attribute settings. The «Информация» section reaches a screen listing the EXIF attributes with visibility checkboxes and label fields («отметить все»/«снять все»); the choice is stored in the profile's photo_info preferences, using the same shape as web, so the two clients stay in sync.

API operations backing these panels (all already served by the backend):

• PATCH /api/albums/:id (title, description, cover_photo_id / clear_cover), DELETE /api/albums/:id, GET /api/albums/:id/members, GET|POST|DELETE /api/albums/:id/share
• POST /api/photo-batch/copy, POST|DELETE /api/photos/:id/tags, GET /api/tags?q=
• PATCH /api/auth/me/preferences; account payload GET /api/auth/me and photo payloads expose preferences, exif, tags, uploader and download_url.

Device albums and synchronization

The album list mixes the server's albums with the device's own albums (MediaStore buckets). Each card is tagged with its source (Сервер / Телефон), and a linked pair shows the connection both ways: the device album shows → <server album>, the server album shows источник: <device albums>.

• Access. Enumerating device albums needs media read access: READ_MEDIA_IMAGES and READ_MEDIA_VIDEO on Android 13+, or READ_EXTERNAL_STORAGE on Android 12 and lower. The app requests it at runtime; without (or with partial) access the device albums are simply not shown, and server albums keep working.
• Synchronization modes are chosen per device album from the album screen (swipe right, or the settings icon):
  • Выключена (A) — local only. Previews are generated on the device and cached in the app's private cache; the album makes no server requests.
  • Копии оригиналов на сервере (B) — originals stay on the device, copies are uploaded to a chosen server album.
  • Перенос оригиналов на сервер (C) — originals move to the server; the device keeps previews. Freeing space replaces the original in MediaStore only after the user confirms the OS write request, in batches.
• Previews are capped at a 1600px long side (JPEG q80) and generated on the device, including a poster frame for videos.
• Deduplication. A device asset is matched to a server photo by the sha256 of the bytes that leave the device (the server exposes each original's checksum). Content already present is linked instead of re-uploaded; an edited asset is re-uploaded and its previous upload removed; a pure rename is propagated via PATCH /api/photos/:id.
• Deletions. The server photo is deleted only when this client uploaded it, its content is gone from the device and no other linked album still holds it. Photos the client did not upload are never touched, and a photo already gone from the server is only reflected in the local index.
• Background. Synchronization runs on app start and while the app is open (a MediaStore content observer), and periodically in the background via WorkManager. The periodic pass honors the Только Wi-Fi setting. Freeing space in mode C is never automatic — it always waits for the user's confirmation.
• Provenance. Mode C writes a marker into the EXIF of the preview it leaves behind (server album/photo, original hash, mode). After a reinstall the app reads these markers to restore the album link and which uploads are its own; unmarked media is left alone.
• Reversibility. Leaving mode C warns first and offers to fetch the originals back from the server (space permitting); declining keeps previews only. Unlinking an album drops the local link and never deletes photos on the server.

Testing

cd android && ./gradlew test

Unit tests cover URL resolution, error mapping, token refresh, the offline cache/repository fallback, page merging, the object cache key, SSE event parsing/reconnect, HEIC detection, and the panorama camera math. Robolectric Compose tests cover the albums grid/offline banner, the viewer swipe navigation, and upload statuses. Request-level tests cover the album/tag/preferences operations behind the attribute/action panels, and DTO tests cover the rich photo and account payloads (exif, tags, uploader, preferences).

Device-only checks (real server E2E, Wi-Fi-only gating, background continuation, HEIC conversion of a real asset) require a device or emulator.