Versioned document storage

Never overwrite — every save is a new immutable version, so you can always look back, compare, and roll forward to an old state.

The idea

Each edit appends a new version — v1, v2, v3 — rather than mutating the document in place. Old versions are immutable: once written, they never change.

Because every version is kept, you can diff two adjacent versions to see exactly what changed, and you can restore an earlier one. Restore does not rewind history — it appends the old content again as a brand-new version. Storage is either a full snapshot per version, or a base snapshot plus a chain of deltas that saves space at the cost of reconstruction work.

Press play to watch versions accumulate as the document is edited and restored.

How it works

Versions form an append-only log. Each record carries a parent pointer and either the full content (snapshot) or just the delta from its parent. Restoring an old version reads its content and writes it as a new record — history is never deleted.

# Append-only version store (snapshot or delta per record)
def save_version(doc_id, content, parent=None):
    v = next_version(doc_id)              # v1, v2, v3, ...
    record = {
        'doc': doc_id, 'version': v, 'parent': parent,
        'content': content,              # or store delta(parent, content)
        'frozen': True                   # immutable once written
    }
    store.append(record)                  # never overwrite an old record
    return v

def get_version(doc_id, v):
    # snapshots: read directly; deltas: replay base then each delta up to v
    return reconstruct(doc_id, v)

def diff(doc_id, a, b):
    return line_diff(get_version(doc_id, a),
                     get_version(doc_id, b))   # removed / added lines

def restore(doc_id, v):
    old = get_version(doc_id, v)
    # restore APPENDS old content as a new version — history is preserved
    return save_version(doc_id, old, parent=current_version(doc_id))

Cost & trade-offs

Strategy	Detail
Snapshots	Fast reads — any version is one direct fetch; uses more space
Deltas	Compact storage; slower reads — reconstruct by replaying the chain
Read cost	O(1) for snapshots; O(chain length) to replay deltas to a target
Write cost	Append-only: one new record per edit, no in-place update
Immutability / audit	Every version is frozen — full history, diffable, restorable

Watch out for

Unbounded growth. Versions accumulate forever. Without pruning, compaction, or periodic snapshotting, storage and chain length climb without limit.
Restore that destroys history. Rewriting the current record back to an old state erases the audit trail. Restore must append the old content as a new version.
Large binary diffs. Line deltas work for text; for images or PDFs a "delta" can be as big as the file. Store binaries as snapshots or content-addressed blobs.
Concurrent edits. Two writers branching from the same parent can clobber each other. Use an optimistic version check (compare-and-append) so a stale write is rejected, not silently lost.
Deep delta chains. Reconstructing a version far from the base replays every delta. Insert periodic full snapshots to bound replay length.

Worked example

A doc starts as v1 ("Draft. Add intro."). An edit fixes the intro and appends v2 ("Final intro. Add intro." with one line changed). A second edit appends v3 ("Final intro. Add summary."). The author then decides the summary was a mistake and restores v2 — which appends a new v4 whose content equals v2. The doc now reads as it did at v2, but all four versions remain intact: nothing was destroyed, every edit is auditable, and total history is conserved.

Check yourself

1. When you restore an earlier version, what happens to the store?

2. What does the delta strategy trade away compared with full snapshots?

Coach note: if a pick doesn't land, give it another pass — the reasoning is what sticks.