Retry safety
Repeated content requests and progress pushes converge instead of duplicating learner actions.
Offline Literacy Platform
A backend for AI-4AI’s learning app that separates published-content delivery from learner-state reconciliation so both remain correct offline.
The connectivity problem
Learners need lessons and assessments when no network is available, and their progress must survive app restarts and later retries. Meanwhile, administrators can publish, update, or delete content while a device is offline.
One generic “sync” cursor cannot safely represent both concerns. Published content changes by version; learner state changes by server update time and carries different conflict rules.
Two synchronization lanes
The client follows two explicit protocols. Content synchronization distributes immutable published snapshots and deltas. Progress synchronization replays durable client events before pulling authoritative state.
Content cursor: a published content version. It never represents learner progress.
Device versionLast complete content state
ManifestFull or delta + tombstones
Verified assetsChecksum before activation
Learner cursor: the server’s update position for user-owned progress. It never represents content publication.
Progress outboxStable event IDs
Idempotent pushMerge and acknowledge
Authoritative pullChanges after cursor
Correctness rules
- Stable identities outlive versions. Lessons and assessments keep stable IDs while publication versions describe a particular released state.
- Deletion is explicit. Delta manifests carry tombstones, so an offline device can remove content that vanished while it was disconnected.
- Downloads activate only after verification. Signed asset URLs and checksums let the client stage a complete version before switching to it.
- Progress events are replay-safe. Client outbox event IDs make retrying a push idempotent; acknowledged events can be removed locally.
- Push precedes pull. The client first delivers local work, then retrieves authoritative state. Completion is monotonic while other conflicts resolve to server truth.
Engineering outcomes
Bounded transfers
Delta manifests send only changed records and explicit deletions when the client has a known version.
Consistent activation
A device switches content versions only after required records and assets verify successfully.
Clear ownership
The server owns published content and authoritative progress; the device owns its durable unsent outbox.