Replay and ordering
A device replays one project queue at a time in creation order. Different projects may sync concurrently, capped at three to protect battery and API capacity.
Proposed · decision requested
Technical plan: offline project sync
Ship reliable offline capture for field teams without turning every client into a distributed database. Use an append-only local queue, server-authoritative conflict resolution, and a measured rollout behind workspace-level controls.
Recommendation
Approve the queue-and-replay architecture and phased beta plan.
It keeps the API authoritative, reuses our existing event log, and limits the first release to task updates and inspection notes. Defer attachments and simultaneous document editing until field telemetry proves the sync loop is stable.
Success means the field app stays trustworthy.
- 99.9%
- of queued mutations settle within 60 seconds of reconnecting
- < 0.1%
- of mutations require a person to resolve a conflict
- 72 hours
- of fully offline work supported on a standard device
- Zero
- silent data-loss incidents during the private beta
01
Problem
Field work fails where connectivity is weakest—and recovery is invisible.
What users experience
Northstar’s inspection teams work in basements, utility corridors, and rural facilities. Today, a dropped request looks like a saved task until the screen is refreshed. Supervisors discover missing notes hours later, after the technician has left the site.
Why now
Offline reliability is the top blocker in 18 of 31 enterprise evaluations this quarter. The mobile team also plans to replace its ad-hoc request cache in Q4; doing both as one designed system avoids a second migration.
02
Scope
The beta is deliberately narrow enough to observe and reverse.
In scope
- Create and update tasks, inspection notes, and status changes offline
- Cache the last 30 days of assigned project data per device
- Show pending, synced, conflicted, and failed states on every mutation
- Remote disable, queue diagnostics, and workspace-level rollout controls
Not in this release
- Offline attachment uploads or media transcoding
- Collaborative rich-text editing or peer-to-peer device sync
- Full project export, billing changes, or account administration
- Desktop web offline mode
- Goals
- Prevent silent data loss, make sync state visible, and preserve one server-authoritative project history.
- Target users
- Field technicians working through long connectivity gaps and supervisors reviewing their completed inspections.
- Assumptions and boundaries
- Devices reconnect within 72 hours; server APIs remain reachable after reconnect; attachments and rich-text collaboration stay out of beta.
- Security
- Encrypt queued payloads with a device-bound key and erase them on remote sign-out.
- Compatibility
- Support the current and previous two mobile releases during the beta.
- Operations
- No new stateful service in the critical path before general availability.
03
Architecture
Clients record intent locally; the existing API remains the source of truth.
- On device Northstar mobile Validates input and assigns an idempotency key.
- Encrypted SQLite Mutation queue Stores ordered intent plus its base revision.
- Existing service Sync API Authenticates, deduplicates, and applies policy.
- System of record Project event log Appends accepted changes and emits canonical state.
Conflict policy
Status transitions use domain rules; scalar task fields use revision-aware last-write-wins; note bodies fork visibly when both sides changed.
Failure handling
Retry transient failures with jitter. Stop on authorization or validation errors, preserve the draft, and show the user a specific recovery action.
Observability
Record queue age, attempts, settle time, conflict class, and client version. Never include note text or customer payloads in telemetry.
04
Milestones
Each phase ends with evidence, not percentage-complete reporting.
| Phase | Target | Owner | Deliverable and exit criterion | Depends on |
|---|---|---|---|---|
| 1 · Prove | 7 Aug | Maya | Replay prototype passes airplane-mode and duplicate-request fault tests. | Security key review |
| 2 · Foundations | 4 Sep | Ishan | Queue, sync endpoint, telemetry, and remote kill switch work in staging. | Event log capacity test |
| 3 · Team pilot | 2 Oct | Priya | Twenty internal users complete a five-day scripted field trial with no lost intent. | Support runbook |
| 4 · Private beta | 30 Oct | Jon | Five design partners meet settle-time and conflict targets for two weeks. | Partner agreements |
| 5 · Harden | 4 Dec | Maya | Go/no-go review has SLO evidence, rollback drill results, and a GA scope proposal. | Beta telemetry |
05
Risks
Ranked by current exposure after mitigation.
| Risk | Likelihood | Impact | Mitigation and trigger | Owner |
|---|---|---|---|---|
| Conflict rules surprise users | Likely | High | Test with real work orders; pause rollout if manual resolution exceeds 0.1%. | Priya |
| Queue payload exposed on a lost device | Unlikely | Critical | Device-bound encryption and remote wipe; block beta on failed key extraction test. | Elena |
| Reconnect storm overloads the API | Possible | High | Jitter, concurrency caps, and load test at 10× forecast before the team pilot. | Ishan |
| Support cannot diagnose stuck work | Possible | Medium | Redacted queue diagnostics and a drill; delay beta if median diagnosis exceeds 15 minutes. | Jon |
| Attachment demand expands scope | Likely | Low | Publish the boundary in beta onboarding; revisit only after core SLOs hold for four weeks. | Priya |
06
Decisions
Recorded choices keep settled tradeoffs from reopening by accident.
-
D-01 · Accepted
Keep the server authoritative
- Alternative
- Replicate project state and resolve it primarily on each client.
- Rationale
- Queued commands fit current domain rules and operations skills.
- Consequences
- The API stays authoritative; offline queries remain deliberately limited.
- Revisit when
- Desktop and mobile both require multi-day offline editing.
-
D-02 · Accepted
Use encrypted SQLite, not a custom log file
- Alternative
- Maintain a smaller custom append-only file format.
- Rationale
- Transactions, migrations, and bounded queries matter more than binary size.
- Consequences
- The client accepts modest storage and binary overhead for safer recovery.
- Revisit when
- Measured storage overhead exceeds 15% on supported devices.
-
D-03 · Accepted
Fork conflicting notes instead of merging text
- Alternative
- Automatically merge note bodies with CRDT or operational transforms.
- Rationale
- A visible duplicate is safer than an invented merge for compliance records.
- Consequences
- Users resolve rare forks explicitly; rich-text collaboration stays out of beta.
- Revisit when
- A structured merge can demonstrate zero semantic loss in field trials.
-
D-04 · Proposed
Gate rollout by workspace
- Alternative
- Gate by account, user cohort, or mobile application version.
- Rationale
- Workspace controls align support, telemetry, and customer consent.
- Consequences
- Phase 1 must freeze a workspace-control API and a minimal admin surface.
- Revisit when
- Pilot telemetry shows workspace-level targeting is too coarse.
07
Open questions
Every unknown has an owner, a date, and a decision it unblocks.
-
How long may regulated customers retain encrypted offline notes?
Unblocks the queue retention default and remote-wipe policy.
- Owner
- Elena
- Due
- 31 Jul
-
Can beta partners exclude specific projects from device caching?
Unblocks workspace controls and partner onboarding copy.
- Owner
- Priya
- Due
- 5 Aug
-
What API headroom is reserved for reconnect traffic?
Unblocks concurrency caps and the Phase 2 capacity test.
- Owner
- Ishan
- Due
- 7 Aug
-
Which five partners represent the hardest connectivity conditions?
Unblocks the private-beta cohort and field test plan.
- Owner
- Jon
- Due
- 14 Aug
08
Review checklist
Close the review only when the plan is specific enough to execute and reverse.
- Scope, non-goals, target users, assumptions, and success measures are explicit.
- Architecture labels match the prose, with failure behavior and trust boundaries named.
- Every milestone has an owner, dependency, deliverable, and evidence-based exit criterion.
- Every risk and open question has an owner, trigger or due date, and a clear unblock.
- Accepted decisions record alternatives, consequences, and a condition for revisiting.