Offline-First Field Survey

Project roadmap

1. 01

   Design the system

   ~2.5h

   Write ARCHITECTURE.md describing: the survey form (defined as JSON with fields such as text, number, choice, date and required rules), the submission lifecycle (draft, queued, uploading, uploaded, rejected), what's stored and encrypted on the phone, and the upload API. Each submission gets a random UUID when created, used as its idempotency key. Done when: the document covers every state and what happens when an upload fails at each point.

2. 02

   Build the Ktor server

   ~2.5h

   Build a small Ktor server with POST /submissions that validates the submission against the same form rules and stores it (in a database or file). When the same UUID is sent again, return the original result without saving a second copy. Return 400 with field errors for invalid data, and require an API token. Done when: sending the same submission twice stores it once, and both calls succeed.

3. 03

   Render and validate forms

   ~3h

   In the Android app, render the form from its JSON definition with Jetpack Compose: the right input for each field type, required markers, and error messages shown under each field as the user types. Save drafts automatically so nothing is lost if the app closes. Share the validation rules with the server logic, so both agree. Done when: the form can't be submitted with invalid data, and drafts survive closing the app.

4. 04

   Store submissions encrypted

   ~2.5h

   Save submissions in Room with their status and attempt count. Encrypt the answers before storing them, using a key kept in the Android Keystore (for example with Google Tink or javax.crypto AES-GCM), so they can't be read by copying the database file. Show the queue with each submission's status. Done when: the database file contains no readable answers, and the app still shows them correctly.

5. 05

   Upload with WorkManager

   ~3h

   Create a CoroutineWorker that uploads queued submissions one by one with the Ktor client, scheduled with a network-connected constraint and exponential backoff. Mark a submission uploaded only after the server confirms. Mark 400 responses as rejected with the reason (retrying won't help), and retry network errors and 5xx responses. Done when: submissions made offline upload by themselves once the phone is back online.

6. 06

   Handle interruptions and edge cases

   ~2h

   Make sure an upload interrupted after the server saved it but before the phone got the answer is simply retried and recognized by its UUID. Recover submissions stuck in uploading when the app restarts. Let the user fix and resend rejected submissions. Show the time of the last successful sync. Done when: turning airplane mode on during uploads never creates duplicates on the server.

7. 07

   Test it

   ~2.5h

   Write tests: the form validation rules, Room DAO tests, a WorkManager test with TestListenableWorkerBuilder against a fake server that fails, times out or accepts, and Ktor server tests with testApplication for idempotency and validation. Done when: all tests pass, and a manual airplane-mode test uploads everything exactly once.

Resources

• DocsAndroid: build an offline-first app
• DocsWorkManager documentation
• DocsRoom documentation
• DocsAndroid Keystore system
• DocsKtor server documentation