# Example: Mobile App Specification

Scope shape: offline field inspection capture in a native mobile application.
This shape carries risk the other two examples do not: the client holds
authoritative state before sync, the network is optional, permissions are
revocable at any moment, background execution is bounded by the operating system,
and old app versions keep running because updates cannot be forced.

Values here are illustrative. Reuse the structure, not the names.

## 1. Requirement Overview

**Background.** Inspectors record equipment checks on paper at sites with no
usable connectivity and re-enter them the next morning. Transcription loses about
one form in twenty, and photo evidence is routinely lost because it never leaves
the personal camera roll.

**In scope.** Offline creation and editing of inspection reports, local photo
capture attached to a report, deferred sync with explicit conflict resolution,
sync status visibility, and minimum-version gating for schema-breaking changes.

**Out of scope.** Inspection scheduling, equipment master data editing, the
web-side review workflow, and any change to the server's report model beyond the
sync contract below.

**Roles.** `Inspector` creates and edits own reports on the device.
`Supervisor` additionally views a team roll-up, read-only on mobile.

**Glossary.**

- *Draft*: a report existing only in local storage, never sent to the server.
- *Pending Report*: a locally complete report queued for upload.
- *Sync Cycle*: one attempt to upload all Pending Reports and refresh assignments.
- *Conflict*: the server holds a newer revision of a report the device also
  changed since its last successful sync.
- *Local Retention Window*: how long a synced report and its photos remain on the
  device before local cleanup.

## 2. Data Model and Interface Contract

**Local store `report`** (device, SQLite)

| Column | Type | Null | Note |
| --- | --- | --- | --- |
| `local_id` | uuid | no | generated on device, primary key |
| `server_id` | string | yes | null until first successful upload |
| `assignment_id` | string | no | which scheduled check this answers |
| `state` | text | no | `DRAFT`, `PENDING`, `SYNCED`, `CONFLICT` |
| `payload` | json | no | answers, schema-versioned |
| `schema_version` | int | no | payload contract version |
| `base_revision` | int | yes | server revision this edit is based on |
| `updated_at_device` | timestamp | no | device clock, may be wrong |
| `attempt_count` | int | no | consecutive failed upload attempts |

**Local store `photo`** (device)

| Column | Type | Null | Note |
| --- | --- | --- | --- |
| `local_id` | uuid | no | primary key |
| `report_local_id` | uuid | no | owning report |
| `file_path` | text | no | app-private storage, not the shared gallery |
| `upload_state` | text | no | `PENDING`, `UPLOADED`, `FAILED` |
| `byte_size` | int | no | pre-compression size |

**Sync contract**

`POST /v1/reports/sync` accepts
`{ deviceId, appVersion, schemaVersion, reports: [{ localId, serverId?, assignmentId, payload, baseRevision? }] }`
and returns
`{ results: [{ localId, status: 'ACCEPTED' | 'CONFLICT' | 'REJECTED', serverId?, revision?, serverPayload?, errorCode? }], minSupportedAppVersion, serverSchemaVersion }`.

Photos upload separately via `POST /v1/reports/{serverId}/photos` as multipart,
one request per photo, after the owning report is `ACCEPTED`.

`GET /v1/assignments?since` returns assignments for offline pre-caching.

The response always carries `minSupportedAppVersion`, so a client learns it is
obsolete from an ordinary sync rather than needing a separate check.

## 3. Surface Specification: Mobile Application

**Skeleton.** Assignment list -> report form (multi-step) -> photo capture ->
sync status screen. A conflict resolution screen is reachable from the
assignment list and from the sync status screen.

**Component granularity.**

- *Assignment list* owns offline-first read from the local store and never blocks
  on the network.
- *Report form* owns answer state and local autosave. It writes to the local store
  on every step transition, not on final submit.
- *Photo capture* owns permission acquisition, compression, and local file
  writing. It returns a `local_id` and never holds image bytes in memory beyond
  the capture.
- *Sync engine* is not a screen. It owns queueing, retry, and conflict marking.
  No screen uploads directly.
- *Sync status screen* owns presentation of queue state and manual retry only.

**Report lifecycle state machine.**

`(none) -> DRAFT` on form start.
`DRAFT -> DRAFT` on every autosave; a draft is never lost by navigation or app
kill.
`DRAFT -> PENDING` when the inspector marks the report complete. This requires no
connectivity.
`PENDING -> SYNCED` on `ACCEPTED`, once all owned photos reach `UPLOADED`.
`PENDING -> CONFLICT` on `CONFLICT`.
`PENDING -> PENDING` on transport failure, with `attempt_count` incremented.
`CONFLICT -> PENDING` after the inspector resolves by keeping local changes.
`CONFLICT -> SYNCED` after the inspector resolves by accepting the server version.
`SYNCED` is terminal until local retention cleanup removes the row.

**Actions and guards.**

| Action | Role | Disabled when |
| --- | --- | --- |
| Start report | Inspector | assignment already has a non-`SYNCED` report |
| Mark complete | Inspector | any required answer missing |
| Capture photo | Inspector | camera permission denied, or report is `SYNCED` |
| Manual sync | Inspector, Supervisor | a Sync Cycle is already running |
| Resolve conflict | Inspector | report is not `CONFLICT` |
| View team roll-up | Supervisor only | no cached roll-up and device offline |

**Offline and connectivity constraints.**

- Every screen except the team roll-up is fully usable offline. Offline is the
  default assumption, not a degraded mode.
- The app never shows a blocking spinner for a network call an inspector did not
  initiate.
- Sync status is always visible as a persistent indicator with the Pending count.

**Platform constraints.**

- Photos are written to app-private storage, never to the shared gallery.
- Background sync uses the platform's deferred job mechanism and must assume the
  operating system may not run it for hours. It is an optimization; foreground
  sync is the guaranteed path.
- Runtime permissions may be revoked between launches, so every capture rechecks
  rather than trusting a cached grant.

## 4. Business Rules

- **BR-01.** A Draft is autosaved on every step transition and survives app
  termination, device restart, and app update.
- **BR-02.** `local_id` is generated on the device, so a report has a stable
  identity before it ever reaches the server. Upload is idempotent on `local_id`.
- **BR-03.** Marking a report complete requires no connectivity and always
  succeeds locally when required answers are present.
- **BR-04.** Reports upload in creation order. A single failing report does not
  block the rest of the queue.
- **BR-05.** A report is `SYNCED` only when the report is `ACCEPTED` *and* every
  owned photo is `UPLOADED`. A report with a failed photo stays `PENDING`.
- **BR-06.** Conflicts are resolved by the inspector, never automatically.
  Last-write-wins is not permitted, because the discarded revision is field
  evidence.
- **BR-07.** The device clock is untrusted. `updated_at_device` is diagnostic
  only; ordering and conflict decisions use `base_revision` and server revisions.
- **BR-08.** Retry uses exponential backoff with a ceiling. After the configured
  attempt ceiling the report stays `PENDING` and surfaces for manual action rather
  than retrying forever.
- **BR-09.** Camera permission is rechecked at every capture. A denied permission
  degrades to a report without photos; it never blocks report completion.
- **BR-10.** Photos are compressed before local write, and a single report's total
  photo payload is capped. The cap is stated during capture, not at sync time.
- **BR-11.** When the sync response reports `minSupportedAppVersion` above the
  running version, the app blocks new report creation, still allows upload of
  existing Pending Reports, and prompts for update. Data is never stranded by
  version gating.
- **BR-12.** A `SYNCED` report and its photos are removed from the device after
  the Local Retention Window. Nothing is deleted while any owned photo is not
  `UPLOADED`.
- **BR-13.** Local storage below the configured floor blocks new photo capture
  before it blocks report creation, since a report without photos is still useful.

## 5. Exception Scenarios

- **E-01.** No connectivity during a Sync Cycle. Sync indicator shows "Waiting
  for network. {n} reports pending." No error dialog. Code `SYNC_OFFLINE`. This is
  an expected state, not a failure.
- **E-02.** Server returns `CONFLICT`. Report shows a conflict badge and the
  assignment list surfaces "Needs your review." Code `REPORT_CONFLICT`. The local
  revision is retained in full until resolution.
- **E-03.** Server returns `REJECTED` for an invalid payload. Report shows "This
  report could not be accepted." with the server reason. Code
  `REPORT_REJECTED`. The report leaves the retry queue and awaits editing.
- **E-04.** Photo upload fails after the report is accepted. Report stays
  `PENDING` with "Photos still uploading ({k} left)." Code `PHOTO_UPLOAD_FAILED`.
- **E-05.** Camera permission denied. Capture screen shows "Photos are disabled.
  You can still complete this report." with a link to system settings. Code
  `PERMISSION_CAMERA_DENIED`.
- **E-06.** Camera permission revoked between launches while the report has
  existing photos. Existing photos are retained and still upload; new capture is
  blocked. Code `PERMISSION_CAMERA_REVOKED`.
- **E-07.** Device storage below the floor. Capture blocked with "Not enough space
  for photos. Free space or sync pending reports." Code `STORAGE_LOW`.
- **E-08.** App version below `minSupportedAppVersion`. Blocking prompt "Update
  required to create new reports." with upload of existing Pending Reports still
  running. Code `APP_VERSION_UNSUPPORTED`.
- **E-09.** Local `schema_version` older than `serverSchemaVersion` for a queued
  report. The server migrates on accept when possible; otherwise it returns
  `REJECTED` with `SCHEMA_UNSUPPORTED` and the report requires the updated app.
- **E-10.** Background job never runs before the inspector opens the app. No
  message. The foreground Sync Cycle handles the queue on launch.
- **E-11.** App terminated mid-upload. On next launch the queue resumes from
  local state; because upload is idempotent on `local_id`, no duplicate report is
  created. Code path is silent to the inspector.
- **E-12.** Device clock significantly wrong. No user-visible message; ordering
  and conflict decisions ignore the device clock per BR-07.
- **E-13.** Supervisor opens the team roll-up offline with no cached data. Empty
  state "Team view needs a connection." Code `ROLLUP_REQUIRES_NETWORK`. This is
  the one screen allowed to require connectivity.

## 6. Acceptance Criteria

**Inspector**

- **AC-01** (BR-01, normal). Given a half-completed report, when the app is force
  terminated and relaunched, then the report reopens at the last completed step
  with all answers intact.
- **AC-02** (BR-03, E-01, normal). Given airplane mode, when the inspector marks
  a report complete, then it becomes `PENDING` locally, the pending count
  increments, and no error is shown.
- **AC-03** (BR-05, E-04, boundary). Given an accepted report with three photos
  where one upload fails, when sync finishes, then the report stays `PENDING` and
  displays one photo remaining.
- **AC-04** (BR-06, E-02, exception). Given the server holds a newer revision,
  when sync returns `CONFLICT`, then the report is marked `CONFLICT`, both
  revisions are viewable, and nothing is overwritten until the inspector chooses.
- **AC-05** (BR-06, normal). Given a `CONFLICT` report, when the inspector keeps
  local changes, then the report returns to `PENDING` with a refreshed
  `base_revision` and re-uploads on the next cycle.
- **AC-06** (BR-02, E-11, boundary). Given an upload interrupted by app
  termination, when the app relaunches and syncs, then exactly one server report
  exists for that `local_id`.
- **AC-07** (BR-04, boundary). Given five Pending Reports where the second is
  `REJECTED`, when the Sync Cycle runs, then the other four reach `SYNCED` and
  only the second remains for editing.
- **AC-08** (BR-09, E-05, exception). Given camera permission denied, when the
  inspector opens capture, then the guidance is shown, and marking the report
  complete still succeeds.
- **AC-09** (BR-09, E-06, exception). Given permission revoked between launches
  with two photos already captured, when the app relaunches and syncs, then both
  existing photos upload and new capture is blocked.
- **AC-10** (BR-13, E-07, boundary). Given storage below the floor, when the
  inspector attempts capture, then capture is blocked while starting and completing
  a report without photos still works.
- **AC-11** (BR-11, E-08, boundary). Given a running version below
  `minSupportedAppVersion` with two Pending Reports, when the app syncs, then the
  update prompt blocks new report creation and both pending reports still upload.
- **AC-12** (BR-10, boundary). Given photos that would exceed the per-report cap,
  when the inspector attempts one more capture, then the cap is stated at capture
  time and no oversized payload is queued.
- **AC-13** (BR-12, normal). Given a `SYNCED` report past the Local Retention
  Window with all photos `UPLOADED`, when cleanup runs, then the report and its
  local files are removed and the server copy is untouched.

**Supervisor**

- **AC-14** (E-13, exception). Given an offline device with no cached roll-up,
  when the supervisor opens the team view, then the empty state is shown and no
  other screen becomes unusable.

## 7. Open Questions and Decision Record

**Open.**

- Local Retention Window length. Owner: Field Operations. Blocks the BR-12
  configuration value, not the cleanup implementation.
- Per-report photo cap and compression target. Owner: Field Operations with
  Platform. Blocks the BR-10 constants.
- Whether `Supervisor` roll-up should pre-cache for offline use in a later
  iteration. Owner: Product. Explicitly out of scope now per E-13.

**Decided.**

- Conflicts are resolved by a human. Last-write-wins was rejected because the
  discarded revision is field evidence that cannot be recovered.
- Report identity is generated on the device. Server-assigned ids were rejected
  because they make offline creation and idempotent retry impossible.
- The device clock is untrusted for ordering. Using it was rejected because field
  devices are routinely wrong by hours after battery replacement.
- Version gating blocks creation but never upload. Blocking both was rejected
  because it would strand completed field work on an obsolete device.
- Background sync is an optimization, not the guaranteed path. Relying on it was
  rejected because neither platform guarantees timely execution.