1. Architecture: local-first, PDS as backup

The IndexedDB on your device is the source of truth. The AT Protocol PDS is a read-replica + multi-device merge point. All edits land locally first; sync is an out-of-band drainer/reader pair.

2. What gets synced

Thirteen lexicons live under cards.decay.flashcard.*. Each one declares a single merge strategy.

3. Sync flow

Four triggers, one scheduler, and a single-flight guard.

Why pull-then-push?

If the drain ran first, a remote update that landed between cycles would briefly disappear: the device would overwrite it with its own local copy. By reading first, the merger has a chance to absorb the remote update, and the drain that follows ships only genuinely new local changes (which now know about the remote state).

4. Merge strategies, by example

Each strategy answers one question: "two records claim to be the same — which fields win?"

Deletes

There are no tombstones. A LWW record that vanishes from the remote listing is hard-deleted locally during the diff phase. Soft-deleted decks carry their own deletedAt and trigger an idempotent cascade that strips child notes, reviewStates, deckPacks, etc.

5. The pack system

A deckPack is one compressed blob holding thousands of notes and their scheduling state — the deltas layer on top.

Shipping a pack

• Encode the payload — JSON, then zstd, then chunk into ≤ 50 MB pieces.
• Mint one deckPart record per chunk (each carries a blob).
• Queue those parts first, then queue the parent deckPack record (which points to them via a parts array).
• The drainer routes blob-bearing puts through individual putRecord+upload calls and the parent record through applyWrites — preserving the order.

Reading a pack

• Pre-pass: every deckPack is materialized before the per-collection merge loop runs.
• Fetch & concatenate the deckPart blobs → verify the contentHash → decompress → fan out into packedNotes and packedReviewState stores.
• Then the regular merge loop runs and per-record updates layer on top via updatedAt LWW.

Why immutable?

A deckPack's content hash is part of its identity. If the hash differs from what we expect, the read aborts rather than silently corrupting state. The deck's currentPack pointer is the only forward-progress lever; bumping it issues a brand new pack record.

6. Blobs & media

Images, audio, and pack chunks all flow through the AT-proto blob API with a small caching layer.

Upload

uploadBlob() runs through a dedicated uploadLimiter (~2 req/sec) so it can't starve record-level XRPC calls. The returned BlobRef is spliced into the record body just before the putRecord / applyWrites call.

Fetch

fetchBlob() goes through the browser's Cache API first, keyed by (did, cid). Cache miss → com.atproto.sync.getBlob, then stash in the cache for future sessions. This keeps already-seen images instantly available across reloads without a custom IndexedDB store.

Pack blobs

Pack and pack-part blobs live in local packsDb / packPartsDb tables as raw Blob objects. The drainer loads them just before shipping and substitutes a BlobRef into the outbox entry. If the source Blob has been deleted locally since the outbox entry was created, the drainer treats the entry as a no-op rather than crashing.

7. Scheduling & rate limiting

Adaptive: the limiter watches PDS response headers and rescales itself.

8. Migration

From phase 1 (no outbox) to phase 2 (outbox-driven), in one pass.

Users who installed the app before the outbox existed have rows that have never been queued for sync. On first sign-in under the new code, a one-shot walk visits every IDB store in dependency order — reviewLog → reviewState → note → noteType → deck → media → settings → deckSettings — and enqueues each record into the outbox.

The outbox does its own coalescing, so even if the user keeps editing during the walk, duplicates collapse before they ship. A flag in syncState marks the walk complete; subsequent app starts skip it entirely. No network traffic until the first scheduler tick.

9. Cheat sheet