Diogramos Android client

Native Android client for Diogramos. Talks to the JSON API at /api/v1/... and the realtime channel at /socket. Sister app to ../../waxx/android — same Compose shell, OKLCh palettes and B612-mono typography, so the two feel like one product family.

The design doc and phase plan live in docs/android.md. Shipped so far: phase 4 — auth, the canvas list, a live render with pan and zoom, and light editing: move, resize, text, colours, add shape, delete, z-order.

Stack

Layer	Choice
Language / UI	Kotlin 2.0 · Jetpack Compose · Material 3
HTTP	Retrofit · OkHttp · kotlinx.serialization
Realtime	com.github.dsrees:JavaPhoenixClient (phase 3)
Storage	EncryptedSharedPreferences (AES via the Android Keystore)
Scanner	com.journeyapps:zxing-android-embedded (ScanContract)
Build	Gradle 9.0 · AGP 8.5.2 · JDK 17
minSdk	26 (Android 8) · targetSdk 34

Single-activity, single-module, no DI framework — dependencies are constructed inline. Adding Hilt when the screen count justifies it is a fine follow-up.

Building

cd android
./gradlew :app:assembleDebug        # → app/build/outputs/apk/debug/app-debug.apk
./gradlew :app:testDebugUnitTest    # JVM unit tests, no emulator needed
./gradlew :app:installDebug         # onto a running emulator or device

The SDK location comes from local.properties (sdk.dir=…), which is not committed. The first build downloads Gradle and a few hundred MB of dependencies; later ones are seconds.

JDK: build with 17–21. AGP 8.5 does not support JDK 25, and lint throws on it with only the version string as the error message, so a build on a modern default JDK fails for reasons that have nothing to do with this code:

JAVA_HOME=/path/to/jdk21 ./gradlew :app:assembleDebug

Running against a local dev server

1. Start Phoenix (mix phx.server); it binds http://localhost:4000.
2. The emulator reaches the host as http://10.0.2.2:4000. A physical device on the same LAN uses the host’s LAN IP.
3. Pair with one of:
   • QR — sign in on the web, Settings → Connected devices → Generate, scan the code. The server picks the URL it encodes from DIOGRAMOS_PUBLIC_URL / X-Forwarded-* / Host, so for emulator testing start Phoenix with DIOGRAMOS_PUBLIC_URL=http://10.0.2.2:4000 or the QR will point at localhost, which on the emulator is the emulator.
   • Magic link — enter the same URL and your email, then read the link out of the dev mailbox at /dev/mailbox and paste it into the second field.

TokenStore upgrades http://<real domain> to https:// on save and load; IPs, localhost and unqualified hostnames are left alone, so the LAN and emulator paths keep working.

Auth

Two paths, because they fail in different situations:

• QR pairing needs a logged-in browser and physical access to its screen. No mail server, no App Links — which is why it leads on self-hosted installs.
• Magic link is the answer for “I’ve only ever used the phone”. It needs the server to send mail, and App Links for the seamless version.

Either yields a bearer token, and the backend treats them identically afterwards. The token is verified with GET /api/v1/users/me before being stored: a scanned QR can name a server this phone cannot reach, and storing it unverified produces an app that fails later with no clue why.

App Links

The https://<host>/m/<token> intent filter is autoVerify="true", which needs /.well-known/assetlinks.json on the server declaring this app’s SHA-256 signing fingerprints (debug and release). Without it the link still works — Android falls back to the default-handler chooser, and the paste box on the magic-link screen always works. The host comes from the appLinksHost placeholder in app/build.gradle.kts, currently diogramos.example.com.

Read the fingerprints with:

keytool -list -v -keystore ~/.android/debug.keystore \
  -storepass android -alias androiddebugkey | grep SHA256
keytool -list -v -keystore release.jks -alias diogramos | grep SHA256

Themes

ui/theme/AppTheme.kt carries all nine daisyUI themes from assets/css/app.css, token for token, with keys matching Diogramos.Themes.all/0.

It holds every token in Themes.color_tokens/0, not just the ones Material needs, because a canvas stores colors as token names and resolves them against the canvas’s own theme. That is what lets a diagram authored in forest render in forest colors while the app chrome stays in whatever the user picked — and it is why these values are copied from the CSS rather than eyeballed.

The two ported modules

canvas/ConnectorGeometry.kt and canvas/DocumentOps.kt are ports of connector_geometry.ex and Document.apply_op/2. Both have to run on the device: connectors re-route on every frame of a drag, and an edit applies optimistically before the server replies. So the same rules necessarily exist twice, and two copies drift silently — nothing throws, the phone just draws or stores something the server wouldn’t.

The Elixir modules are the authority and the ports are pinned to them:

mix diogramos.android_fixtures     # from the repo root

writes connector_geometry.json (360 cases) and document_ops.json (32 cases) into app/src/test/resources/, and the matching tests assert this code reproduces every one — SVG path strings and rejection reasons included. After a deliberate change to the Elixir side, regenerate and commit; a failure for any other reason means the port is wrong.

Realtime

CanvasSocket.subscribe(canvasId) returns a Flow<CanvasEvent>. CanvasSession holds the document and the version, and decides what each incoming op means:

• our own op echoing back (matched on actor_ref) — already applied, so only the version moves;
• the next version in sequence — applied;
• anything else — drift, and the screen refetches the canvas.

There is no OT and no CRDT, because the server has none either: Authority.apply_op/4 takes no client version and applies ops in arrival order, so concurrent edits to one field are last-writer-wins exactly as on the web. Drift after a reconnect is normal and heals silently — the rejoin delivers a fresh snapshot.

Tests

app/src/test/ holds plain JVM tests — no emulator, no Robolectric. That is why PairPayload parses with java.net.URI instead of android.net.Uri: the pairing parser is the one place where a mistake silently stores the wrong server, so it is worth being able to test it directly.

Editing

Tap selects, tapping the selection opens the sheet, dragging moves, and the corner handles resize. Connectors are rendered but not authored here — picking an anchor on a phone is its own design problem, and it is not what mobile users are blocked on.

Edits apply on screen before the server answers, because an edit that waits for a round trip feels broken under a finger. If the server refuses one it is rolled back — unless a later edit is already in flight, in which case undoing it would also undo what came after, and the screen resyncs instead.

A drag doesn’t touch the document while the finger is down: each op costs a server round trip, a broadcast to every peer and a WAL row, so the in-flight geometry is a render-time override and ops go out about ten times a second plus once at the end.

Not yet shipped

Export and the theme picker (phase 5), and the launcher icon and release/F-Droid pipeline (phase 6). See docs/android.md.

Nothing has yet been seen running on a screen: the unit tests cover the geometry, op application, the parser, the viewport maths, the reconciliation rules and the editing maths, but no emulator or device has been available. Neither a rendered diagram, a live connection nor a gesture has been confirmed against a real server — which is the main thing worth doing before trusting the write path.

Nothing has yet been seen running on a screen: the unit tests cover the geometry, the parser and the viewport maths, but no emulator or device was available to confirm a rendered diagram looks right.