HQ for Android

Native Android client for the patilla.es HQ dashboard (/hq). It talks to the backend's JSON API (/hq/api/*, /hq/stream) with a per-device bearer token. The backend repo is patillacode/patilla-dashboard; its docs/API.md is the contract.

The step-by-step setup list for the owner is docs/owner-checklist.html (one offline file, tick-boxes persist).

What it does

• Rooms as swipeable pages (same rooms and widgets as the web HQ, driven by /hq/api/layout): clock, vitals, attention banner, weather, agenda, tasks (tick with undo), shopping (tick and add), launcher, playing, downloads, arrivals, to-watch, music, meme, recipe, YNAB, spending, storage.
• Search tab: apps and services, !bang shortcuts (for example !gh foo), t <text> adds a task, n <text> adds an inbox note.
• Themes (the backend's palettes), Settings (server, theme, sign out).
• Three home-screen widgets: Today (next events and open tasks), Shopping (tick items), Playing (streams and downloads).
• Live updates over one SSE stream, only while the app is on screen.

First login

1. Install (below) and open the app.
2. Server address: https://patilla.es is the default.
3. Enter the HQ password and the 6-digit authenticator code. The server returns a device token that lives in the app's encrypted storage; the password is never stored.
4. With a screen lock set on the phone, the app asks for biometrics or the device PIN when opened. Without one it opens directly.

Privacy and refresh behaviour

• The app makes no background requests by default. Settings has a toggle "Refresh widgets in the background (every 15 min)", default off. With it off, widgets refresh when the app is opened, when a widget is added (one refresh), or when you tick a task in a widget.
• Turning it on schedules a 15-minute WorkManager job that needs a network connection.
• The SSE stream runs only while the app is visible.

App lock

The biometric/PIN gate re-locks after 5 minutes in the background. Tradeoff: while the gate is locked, home-screen widgets stay readable (they show cached data) and ticking a task or shopping item from a widget works without unlocking (there is no undo). Anyone holding an unlocked phone can see widget contents (events, tasks, shopping, streams). Remove the widgets if that matters.

Build

just test         # :core tests (no Android SDK needed)
just check        # core tests + app lint + app unit tests
just build        # debug APK
just dev          # install the debug build on the emulator only
just emu          # boot the emulator (AVD hq-api35)
just shot NAME    # emulator screenshot to .superpowers/shots/NAME.png
just sync-fixtures  # copy ../patilla-dashboard/fixtures/api/*.json
just dev-phone    # OWNER ONLY: install the debug build on the attached physical phone

Needs JDK 21+ and the Android SDK (sdk.dir in local.properties).

Against a local backend: in ../patilla-dashboard run just demo (password demo, code from just demo-code), then on the emulator set the server to http://10.0.2.2:8000 on the login screen.

Alternative to just dev-phone: open the project in Android Studio, select the phone, Run (debug build). The server defaults to https://patilla.es; change it on the login screen only if you point at another backend.

Install

Add https://forgejo.patilla.es/patillacode/patilla-dashboard-android to Obtainium with a read-only Forgejo token (create it in Forgejo under Settings, Applications, with read access to repositories only), and install the latest release (hq-vX.Y.Z.apk). Obtainium updates it from then on.

Release

Work happens on a branch, goes through a PR, is squash-merged to main, then tagged. just release 1.0.0 tags v1.0.0 and pushes it; .forgejo/workflows/release.yml runs the tests, builds the signed APK and attaches it to a Forgejo release. CI (ci.yml) runs on PRs and main.