# galo Android client

Native Android client for a self-hosted [galo](../README.md) 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

```sh
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:

```sh
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:

```sh
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`:

```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 an album screen is active the client holds
`GET /api/sse/albums/:id?token=` and backfills missed changes via
`GET /api/albums/:id/photos?since=` after a reconnect.

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

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

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