synq/docs/android-notes.md

android notes

stack

• kotlin
• jetpack compose
• room
• okhttp or retrofit
• workmanager
• kotlinx serialization or moshi

main screens

capture screen

default screen. should open fast and focus text immediately.

fields:

• body text
• todo checkbox or segmented note/todo control
• tags text field
• save
• save and close
• sync now

do not run network checks before user can type.

history screen

small list of recent captures.

show:

• created timestamp
• first line/body preview
• kind
• tags
• status: pending/synced/failed
• last error when failed
• retry action for pending/failed

settings screen

minimum fields:

• server base url
• bearer token
• device label

defaults:

server base url: http://jeeves.mother:8765
device label: android

local database sketch

capture entity:

data class CaptureEntity(
    val id: String,
    val createdAt: String,
    val kind: String,
    val body: String,
    val tagsJson: String,
    val device: String,
    val status: String,
    val syncedAt: String?,
    val lastError: String?
)

status values:

pending
syncing
synced
failed

save behavior

• trim body.
• if empty, do not save.
• generate id.
• persist row with status pending.
• clear input.
• optionally close if user used save and close.

sync behavior

manual sync and workmanager should share the same sync service.

algorithm:

load pending + failed captures
for each capture:
  post to server
  if accepted or already_seen:
    mark synced
  else:
    mark failed with last_error

do not delete synced captures in v1. keep local history.

workmanager

constraints:

• network available

periodic behavior:

• check /health
• if healthy, sync pending/failed
• if not healthy, exit quietly

do not try to perfectly detect home network in v1. reachability is enough. if it can hit jeeves.mother, it is home/vpn enough.

launch speed

hard rule: no network call before text entry is usable.

load settings and db async. the first rendered thing should be a focused text box.