synq/tasks.org

#+title: synq tasks
#+startup: overview
#+todo: TODO(t!) NEXT(n!) HOLD(h@!) | DONE(d!) CANX(c@!)

* goal
build a tiny android-to-org capture system.

the app must be instant-feeling, capture-only, and boring. the phone stores notes locally, then posts them to a lan-only server. the server appends validated entries to a central org file.

* decisions
- android-only native app.
- kotlin + jetpack compose.
- room sqlite for local queue/history.
- okhttp or retrofit for http.
- workmanager for opportunistic sync.
- python fastapi listener in docker.
- server owns all writes to the canonical org file.
- phone never edits org files directly.
- server dedupes by capture id.
- no nextcloud/file-sync dependency.
- no org parser on phone.
- no public exposure.

* acceptance criteria
- opening the app focuses the text field automatically.
- saving a note works offline and returns the user to an empty entry state.
- captures include local created timestamp with timezone.
- user can mark capture as todo.
- user can add optional tags.
- manual sync posts all pending captures when server is reachable.
- server appends valid captures to `phone.org`.
- duplicate posts do not create duplicate org entries.
- failed sync attempts remain visible and retryable.
- app shows at least pending/synced/failed history.
- service can run in docker on jeeves/unraid.
- service has a `/health` endpoint.
- service rejects missing/invalid auth token.
- service rejects empty capture body.
- service has tests for org formatting and duplicate handling.

* milestone 0: repo setup
** DONE create monorepo skeleton
*** acceptance
- `android/`, `server/`, and `docs/` directories exist.
- root `README.md`, `tasks.org`, `.env.example`, and `docker-compose.example.yml` exist.
*** notes
Skeleton committed in initial commit. android/ dir will be created in milestone 2.
*** evidence
- commit: c08b3fe
- tests: n/a (directory structure)
- datetime: [2026-05-17 Sat 00:00]

** DONE add root gitignore
*** acceptance
- ignores android build outputs.
- ignores python virtualenv/cache.
- ignores sqlite db files.
- ignores local env files.
- does not ignore docs or source files.
*** notes
Standard gitignore covering Python venv/cache, sqlite db files, .env, and Android build outputs.
*** evidence
- commit: c08b3fe
- tests: n/a
- datetime: [2026-05-17 Sat 00:00]

** DONE document v1 scope in README
*** acceptance
- states capture-only scope.
- states non-goals.
- states architecture and build order.
*** notes
README covers non-goals, architecture diagram, v1 behavior, org output format, and build order.
*** evidence
- commit: c08b3fe
- tests: n/a
- datetime: [2026-05-17 Sat 00:00]

** DONE add task template to tasks.org
*** acceptance:
- `*** notes` section for each milestone task, to be used by you to document your decisions and hurdles overcome
- `*** evidence` section with sub bullets:
  - `commit` list of commit hashes on this task
  - `tests` describing tests run (anyone should be able to use these later)
  - `datetime` the task was completed, including timestamp, eg [2026-05-17 Sun 16:06]
*** notes
Template added in 5f387df. All milestone tasks now have notes/evidence blocks.
*** evidence
- commit: 5f387df
- tests: n/a
- datetime: [2026-05-17 Sat 00:00]
* milestone 1: server mvp
** DONE create fastapi app
*** acceptance
- `GET /health` returns 200 with simple json.
- `POST /capture` accepts a valid capture payload.
- auth token is required for `POST /capture`.
*** notes
FastAPI app in server/app/main.py. Auth via Bearer token dependency injected on POST /capture. Health endpoint needs no auth.
*** evidence
- commit: e873a00
- tests: pytest tests/test_api.py::TestHealth, tests/test_api.py::TestCapture — 12 tests, all pass
- datetime: [2026-05-17 Sat 17:00]

** DONE define pydantic capture model
*** acceptance
- requires id, created_at, kind, body, tags, and device.
- kind is constrained to note/todo.
- body is trimmed and must not be empty.
- tags are normalized before formatting.
*** notes
Pydantic v2 model in server/app/models.py. Body is stripped via field_validator; kind uses Literal["note","todo"]. Tag normalization lives in org_writer.py so the model stays a plain schema.
*** evidence
- commit: e873a00
- tests: pytest tests/test_api.py::TestCapture::test_empty_body_rejected, test_invalid_kind_rejected — pass
- datetime: [2026-05-17 Sat 17:00]

** DONE implement org formatter
*** acceptance
- todo captures produce `* TODO ...`.
- note captures produce `* note ...`.
- org property drawer includes created, source, and id.
- tags are emitted as org heading tags.
- multiline note body is preserved.
- tests cover todo, note, tags, empty tags, and multiline body.
*** notes
Pure function format_capture() in server/app/org_writer.py. Single-line notes: heading is "* note", body below drawer. Multiline notes: heading is "* note: <first line>", full body below drawer. Tag normalization strips #, lowercases, replaces spaces with _, removes non-[a-z0-9_] chars, deduplicates.
*** evidence
- commit: e873a00
- tests: pytest tests/test_org_writer.py — 15 tests (7 normalize_tags + 8 format_capture), all pass
- datetime: [2026-05-17 Sat 17:00]

** DONE implement sqlite idempotency store
*** acceptance
- accepted capture ids are stored.
- repeated id returns accepted/already-seen without appending.
- db path is configurable.
*** notes
IdempotencyStore in server/app/store.py. Uses sqlite3 with a seen_ids table. DB path from PHONE_CAPTURE_DB_PATH env var. already_seen() checks before write; mark_seen() inserts after append.
*** evidence
- commit: e873a00
- tests: pytest tests/test_api.py::TestCapture::test_duplicate_capture_returns_already_seen, test_duplicate_not_appended_twice — pass
- datetime: [2026-05-17 Sat 17:00]

** DONE implement append writer
*** acceptance
- appends to configured org path.
- creates file if missing.
- writes utf-8.
- appends exactly one entry per new capture.
- uses file lock or equivalent simple concurrency guard.
*** notes
Append logic in main.py POST /capture handler. Uses a module-level threading.Lock (get_file_lock()) around open(path, "a", encoding="utf-8"). Creates parent dirs if missing. Org path from PHONE_CAPTURE_ORG_PATH env var.
*** evidence
- commit: e873a00
- tests: pytest tests/test_api.py::TestCapture::test_valid_capture_appended_to_org, test_duplicate_not_appended_twice — pass
- datetime: [2026-05-17 Sat 17:00]

** DONE add server tests
*** acceptance
- health endpoint test.
- valid capture append test.
- duplicate capture test.
- invalid token test.
- empty body rejection test.
*** notes
28 tests total across test_api.py (12) and test_org_writer.py (16). All pass. Run with: cd server && python -m pytest tests/ -v
*** evidence
- commit: e873a00
- tests: pytest tests/ — 28 passed in 0.33s
- datetime: [2026-05-17 Sat 17:00]

** DONE containerize server
*** acceptance
- dockerfile builds server image.
- compose example maps `/data`.
- env vars configure token, org file, and sqlite path.
- container starts and exposes configured port.
*** notes
server/Dockerfile uses python:3.11-slim, installs deps, copies app/, exposes 8765. docker-compose.example.yml already existed in root with correct env var mapping. CMD runs python -m app.main via uvicorn.
*** evidence
- commit: e873a00
- tests: n/a (docker build not run in CI; validate manually with: docker build ./server && docker run -e PHONE_CAPTURE_TOKEN=... -p 8765:8765 -v /data:/data <image>)
- datetime: [2026-05-17 Sat 17:00]

* milestone 2: android local capture
** DONE create android project
*** acceptance
- kotlin android app builds.
- jetpack compose enabled.
- min sdk is reasonable for current personal device.
- app id is stable, e.g. `me.hgsky.phonecapture`.
*** notes
Gradle project in android/. AGP 8.7.3, Kotlin 2.0.21, Compose BOM 2024.10.01. minSdk=31, compileSdk=36. App ID is me.hgsky.synq. Open android/ in Android Studio and hit Sync — AS will download the Gradle wrapper (8.9) automatically.
*** evidence
- commit: 19b05a8
- tests: Gradle sync in Android Studio (manual step)
- datetime: [2026-05-18 Sun 17:00]

** DONE build capture screen
*** acceptance
- app opens to multiline text box.
- keyboard opens automatically.
- note/todo control exists.
- tags field exists.
- save button exists.
- save and close affordance exists.
*** notes
CaptureScreen.kt uses LaunchedEffect(Unit) { focusRequester.requestFocus() } for auto-focus. note/todo Switch, tags OutlinedTextField, "save" OutlinedButton (stays), "save & close" Button (finishes activity). No network call on launch.
*** evidence
- commit: 19b05a8
- tests: manual — build and run on device/emulator
- datetime: [2026-05-18 Sun 17:00]

** DONE implement local room database
*** acceptance
- capture entity has id, created_at, kind, body, tags, device, status, synced_at, and last_error.
- saving creates pending row.
- pending captures survive app restart.
*** notes
CaptureEntity, CaptureDao, CaptureDatabase in data/db/. Tags stored as JSON string (kotlinx-serialization). DB name synq.db, singleton via companion object. Room persists across restarts by default.
*** evidence
- commit: 19b05a8
- tests: manual — save a capture, force-close app, reopen and check history
- datetime: [2026-05-18 Sun 17:00]

** DONE implement capture id generation
*** acceptance
- id format is stable and readable, e.g. `phone-yyyymmdd-hhmmss-rand`.
- ids are generated client-side.
- tests or simple assertions prevent blank/duplicate ids in normal flow.
*** notes
generateCaptureId() in data/CaptureId.kt. Format: phone-YYYYMMDD-HHmmss-xxxx (4 random [a-z0-9] chars). Called in CaptureViewModel.save() before Room insert.
*** evidence
- commit: 19b05a8
- tests: manual — check id column in history; each save produces a unique phone-… id
- datetime: [2026-05-18 Sun 17:00]

** DONE implement basic history screen
*** acceptance
- lists recent captures.
- shows pending/synced/failed status.
- failed row shows last error.
- user can retry failed/pending sync.
*** notes
HistoryScreen.kt observes captureDao.observeAll() as Flow. Status colored green/red/grey. Retry button shown for pending/failed; calls updateStatus(id, "pending", null) so the sync worker picks it up in milestone 3.
*** evidence
- commit: 19b05a8
- tests: manual — save captures, navigate to history, verify status labels and retry button
- datetime: [2026-05-18 Sun 17:00]

* milestone 3: android sync
** DONE implement api client
*** acceptance
- base url configurable in app settings or build config.
- bearer token configurable in app settings or build config.
- client can call `/health`.
- client can post capture payload.
*** notes
SynqApiClient in data/api/. OkHttp with 10s timeouts. checkHealth() does GET /health, returns false on any exception so callers never crash. postCapture() maps 401 → failed, non-2xx → failed, already_seen → AlreadySeen, else → Accepted. Uses org.json for request building, kotlinx-serialization for tag decoding.
*** evidence
- commit: 2a963d9
- tests: manual — sync now button, check history screen status
- datetime: [2026-05-18 Sun 18:00]

** DONE implement manual sync
*** acceptance
- sync now posts all pending captures.
- successful posts mark rows synced.
- already-seen response marks row synced.
- failures retain pending/failed status and last error.
*** notes
syncPending() top-level function in data/sync/SyncService.kt — shared by manual sync and WorkManager. CaptureViewModel.syncNow() calls it on Dispatchers.IO, guards with isSyncing flag. Sync icon in top bar shows CircularProgressIndicator while running.
*** evidence
- commit: 2a963d9
- tests: manual — tap sync, verify captures move to synced in history; test with wrong token, verify failed + error message
- datetime: [2026-05-18 Sun 18:00]

** DONE implement opportunistic workmanager sync
*** acceptance
- periodic sync is registered.
- sync only runs when network is available.
- worker first checks `/health`.
- worker does not block capture speed.
*** notes
SyncWorker (CoroutineWorker) in data/sync/. Registered in SynqApp.onCreate() as KEEP unique periodic work (15-min interval, NETWORK_CONNECTED constraint). Health check before sync — exits quietly if server unreachable. Does not touch UI thread.
*** evidence
- commit: 2a963d9
- tests: manual — let app sit on WiFi, verify pending captures eventually sync without manual trigger
- datetime: [2026-05-18 Sun 18:00]

** DONE add simple server reachability settings
*** acceptance
- default url can be set to `http://jeeves.mother:8765`.
- user can change server url.
- user can change token.
- invalid settings do not crash app.
*** notes
SettingsScreen + SettingsViewModel from milestone 2. DataStore-backed. Default serverUrl is http://jeeves.mother:8765. All network calls wrap exceptions so invalid URL/token never crashes — they just produce PostResult.Failed with the error message.
*** evidence
- commit: 19b05a8 (screen), 2a963d9 (wired to sync)
- tests: manual — set bad URL, tap sync, verify captures stay pending/failed with error; set correct URL + token, sync succeeds
- datetime: [2026-05-18 Sun 18:00]

* milestone 4: polish and hardening
** DONE make launch path fast
*** acceptance
- app opens directly to capture field.
- no network call blocks launch.
- no history loading blocks text entry.
*** notes
LaunchedEffect(Unit) { focusRequester.requestFocus() } fires immediately on composition. No network calls in MainActivity or CaptureScreen init path. History loads via Room Flow on a background coroutine — never blocks text entry.
*** evidence
- commit: 19b05a8
- tests: manual — cold launch, keyboard appears without any loading state
- datetime: [2026-05-18 Sun 19:00]

** DONE normalize tags
*** acceptance
- whitespace-separated and comma-separated tags both work.
- invalid org tag chars are stripped or replaced.
- duplicate tags collapse.
*** notes
Two-layer normalization: parseTags() in CaptureViewModel splits on [,\s]+ before storing to Room. normalize_tags() in server/app/org_writer.py lowercases, strips #, replaces spaces with _, removes non-[a-z0-9_] chars, deduplicates. 7 unit tests cover all cases.
*** evidence
- commit: e873a00 (server), 19b05a8 (android)
- tests: pytest tests/test_org_writer.py::TestNormalizeTags — 7 passed
- datetime: [2026-05-18 Sun 19:00]

** DONE fix org formatting
*** acceptance
- add `#+startup: overview` to synq.org
*** notes
Append writer in main.py checks if org file exists before first write. If missing, creates it with #+title and #+startup: overview header. Existing files are never modified.
*** evidence
- commit: (this commit)
- tests: manual — delete synq.org, post a capture, verify header present
- datetime: [2026-05-18 Sun 19:00]

** DONE handle multiline notes well
*** acceptance
- first line can become note heading if body is multiline.
- full body is preserved under heading.
- todo body remains usable as a single todo heading, with extra lines under it if present.
*** notes
format_capture() in org_writer.py: multiline note uses first line as heading suffix ("* note: <first line>"), full body preserved below drawer. Single-line note uses "* note" heading, body below. Covered by test_note_multiline.
*** evidence
- commit: e873a00
- tests: pytest tests/test_org_writer.py::TestFormatCapture::test_note_multiline — passed
- datetime: [2026-05-17 Sat 17:00]

** DONE add basic logs
*** acceptance
- server logs accepted capture id.
- server logs duplicate capture id.
- server logs rejected payload without dumping secrets.
*** notes
logger.info for accepted and duplicate (id only, no body). logger.warning for invalid token (client IP only, no token value logged). logger.warning for validation errors (field names only, no body content).
*** evidence
- commit: (this commit)
- tests: manual — send bad token, send empty body, check uvicorn stdout
- datetime: [2026-05-18 Sun 19:00]

** DONE create backup note
*** acceptance
- readme documents which paths need backup.
- readme documents restore behavior.
*** notes
Added "backup" section to README.md covering synq.org, capture.sqlite3, token.txt. Restore section documents behavior when each file is lost individually.
*** evidence
- commit: (this commit)
- tests: n/a
- datetime: [2026-05-18 Sun 19:00]

* milestone 5: optional v1.5
** TODO add android share target
*** acceptance
- sharing text to app opens prefilled capture.
- user can save as note or todo.
** TODO add home screen quick capture widget
*** acceptance
- widget opens capture screen quickly.
- does not require sync to work.
** TODO add recent tag chips
*** acceptance
- app shows recent tags.
- tapping chip adds/removes tag.
** TODO add edit-before-sync
*** acceptance
- pending/failed captures can be edited.
- synced captures are read-only unless explicitly duplicated.

* implementation notes for coding agents
- keep the server small and testable.
- keep org formatting in one pure function.
- do not add auth flows, accounts, or public hosting.
- do not add org parsing.
- do not write to org files from android.
- prefer boring explicit settings over clever discovery.
- if a design choice risks sync conflicts, do the simpler append-only thing.