initial commit

2026-05-17 15:59:43 -04:00
commit c08b3fe80d
9 changed files with 883 additions and 0 deletions
--- a/docs/android-notes.md
+++ b/docs/android-notes.md
@@ -0,0 +1,130 @@
+# 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:
+
+```text
+server base url: http://jeeves.mother:8765
+device label: android
+```
+
+## local database sketch
+
+capture entity:
+
+```kotlin
+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:
+
+```text
+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:
+
+```text
+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.