Offline service notes
CJ Ackley | SWE | Project brief

STATUS
Offline workflow brief; record ownership to define. Implementation and tests are planned.

THE PROBLEM
A technician needs asset details and a checklist in a room with poor reception. Notes should remain available after a normal app restart. Reconnecting must not silently overwrite another technician's edit or submit the same visit twice.

DESIGN QUESTION
How does the technician know what is saved locally, synced, or waiting for a decision?

SCOPE
- Build an installable web app with IndexedDB storage and an explicit outbox.
- Sync through a REST API using operation IDs and record versions; surface conflicting edits.
- Cache assigned visits and asset details; keep the first release to text and checklist data.

CONSTRAINTS
Users: Assigned technicians and a dispatcher
Conflicts: Review version conflicts; no silent last-write-wins
Storage: Show pending work and provide export; browser storage may be evicted
Access: Server authorization applies to every synchronized record

ENGINEERING DECISIONS (PROPOSED)
Local transactions and sync conflicts
Save the edited note and its outbox operation in one IndexedDB transaction. The API commits the operation ID and record update together. A repeated operation returns the original outcome; a version conflict keeps both drafts available for review.

ALTERNATIVE
Automatic field merging reduces interruptions, but can combine a checklist and note into a record neither technician intended.

TRADEOFF
Conflicts require a person to resolve them. The interface must distinguish saved locally, pending, rejected, and confirmed without making the technician inspect a sync log.

PROPOSED TOOLS AND METHODS
TypeScript, IndexedDB, REST API, PostgreSQL

VERIFICATION SCENARIO (NOT YET RUN)
Two devices finish the same visit offline
Start both devices from the same visit version, edit independently, reconnect one, then interrupt and retry the other during synchronization.

PASS CONDITION
One update is accepted; the other becomes an explicit conflict. Both drafts remain readable, and retrying a confirmed operation does not create another note.

EVIDENCE TO RETAIN
A two-browser test, persisted outbox records, API transaction assertions, and a short recording of the conflict-resolution flow.

MEASUREMENT AND LIMITS
Test browser restart, quota failure, expired authentication, and revoked assignment separately. Show unsynced work before sign-out. A local draft cannot be recovered after browser storage is evicted unless it was exported or synchronized.

COMPLETION CRITERIA (PLANNED)
- A technician can complete a seeded visit offline and confirm its server receipt later.
- Duplicate operations, two-device conflicts, and denied writes have repeatable tests.
- Keyboard navigation, status announcements, and draft export are checked in the client.

VERIFICATION PLAN
Disconnection
Save offline, restart normally, and reconnect; the note appears once.

Concurrent edits
Edit one record on two devices; neither change disappears silently.

Revoked access
Reject an unauthorized sync and preserve an exportable local draft.

PLANNED DELIVERABLES
- Offline web client, API, and synchronization protocol
- Two-client conflict tests and interrupted-sync scenarios
- Local deployment, sample visits, and storage-recovery instructions

SCOPE NOTE
Offline drafts depend on retained device storage. Export and sync status need to stay visible; photo uploads are outside the first release.

NEXT STEP
Define visit states, record ownership, and the conflict-resolution screen.
