The Tolstoy PWA, examined

Part 1How the sync model actually works

The sync model has three independent pieces that people often conflate. Let me separate them.

Piece A — What's being synced

Only your annotations, not the books. The books (works + wiki articles) are public files on tolstoy.life — you download them fresh from the origin when you want to read offline. The only mutable user-owned data is your annotations: bookmarks, highlights, notes, reading position, tags. That's maybe tens of kilobytes for a casual reader, maybe 5–15 MB for a power user after years.

So "sync" means: keep that small blob of annotations in agreement between your phone, your laptop, and wherever else you read. Nothing else is synced.

Piece B — How the conflict-free merge works (the CRDT)

The annotations are stored locally in a thing called a Y.Doc (a Yjs document — Yjs is a well-known open-source CRDT library). A CRDT is a data structure where two people can edit offline, come back online, and the merge is deterministic — no "resolve merge conflict" dialog, no "the server decides." Both sides converge to the same state by math.

Practically: every change you make to an annotation becomes an operation (an op) — "inserted text here", "set body to X", "deleted annotation Y." Ops carry a little metadata (which device, a logical clock). When two devices exchange ops, Yjs replays them in a well-defined order and both end up with the same final state.

This Y.Doc is persisted to your browser's IndexedDB via a library called y-indexeddb. So "your annotations" live in IndexedDB on your phone and in IndexedDB on your laptop — each is a complete, authoritative copy.

Piece C — How devices find each other (the relay + pairing)

For two devices to exchange ops, they need a rendezvous point. That's the sync relay: a tiny Cloudflare Worker + Durable Object. It's a "dumb pipe" — its entire job is to forward opaque binary blobs from phone to laptop and vice versa. It doesn't parse your annotations; it doesn't know if you're annotating War and Peace or Anna Karenina; it just sees "room ID X received 4 KB of bytes, forward to the other device connected to room X."

A "room" is just a UUID. Your annotations live in your room. Two things are needed to connect to your room:

1. The room ID (a UUID)
2. The sync key (a random 256-bit secret, used to HMAC-sign your messages so the relay knows you belong there)

There's no account, no email, no password. The key is your identity.

The pairing flow

How a second device gets the room ID and sync key without a server to look them up:

1. Phone (already set up) generates a QR code. Inside the QR code is a URL: https://tolstoy.life/pair#room=<id>&key=<key>&did=<deviceid>&exp=<5min>&sig=<hmac>.
2. Everything after the # (the "URL fragment") stays client-side — browsers don't send fragments to servers, so tolstoy.life's logs see only /pair, never the key.
3. Laptop scans the QR (via camera) or the user types in a BIP-39 six-word phrase on a phone call.
4. Laptop opens the URL, extracts the fragment, does a confirmation handshake with the phone via the relay.
5. Laptop now has room ID + sync key → connects to the relay → Yjs reconciles both sides → laptop has your annotation history.

That's the whole sync model. The elegance is that the server is trivial (~150 lines of TypeScript), carries no secrets, can be thrown away and rebuilt, and can never leak user data it doesn't have.

Part 2What lives on device — and what a cache clear takes with it

Books and annotations both persist on device, but in different browser APIs with different cleanup triggers. Worth making explicit because "clear cache" means different things in different places.

Storage topology

Once a work is downloaded for offline reading, here's where each piece actually lives:

Cache API and IndexedDB are both persistent browser storage, both sit under the navigator.storage quota, both survive app closes, reboots, and OS updates. They're separate APIs because they're optimised for different things: Cache API speaks HTTP (request → response), so the service worker can serve from it on every navigation; IndexedDB is for structured data with indexes.

Importantly, Cache API is not the browser's HTTP cache despite the confusing name.

The scenarios

1 · Clearing the browser's HTTP cache

Chrome → "Cached images and files", Firefox → "Cached Web Content". Nothing lost. HTTP cache is separate from both Cache API and IndexedDB. This is the safe one.

2 · Clearing "site data" / "Cookies and other site data"

Chrome or Firefox. Everything for tolstoy.life goes. Cache API + IndexedDB + localStorage + service worker, all wiped together.

3 · Safari → "Clear History and Website Data"

macOS or iOS Settings. Same as scenario 2 — a full origin-bucket wipe. Safari doesn't let you clear only part of it.

4 · iOS 7-day ITP auto-eviction

Uninstalled PWA, no interaction for 7 days. Same as scenario 2, but silent.

5 · User removes PWA from home screen

iOS: data usually survives in Safari's shared origin bucket. Android: depends on OS version; uninstalling through the app manager typically wipes it.

What survives a site-data wipe

The load-bearing insight

Books are always recoverable — they're public-domain files on the origin. Annotations are the only data that can be truly lost if the user hasn't exported and hasn't enabled sync with another device.

This is why the architecture relies on three defences for annotations: (1) JSON-LD export, (2) device sync as defence-in-depth, (3) encrypted backup to a user-controlled URL. Any one of them is enough.

Part 3Installing the app — the UX problem

The 7-day eviction story in Part 2 means one thing: installing the PWA to the home screen is not an optional power-user feature. It's the difference between a library that survives and one that quietly disappears after a week on iOS. Which makes the install UX the single most important piece of onboarding this project has.

And install UX is platform-fractured. Each operating system handles it differently — some let you prompt programmatically, some don't, one of them (iOS) treats PWAs as a second-class citizen entirely. The site has to detect what's possible and render the right flow for each.

Device landscape

The decision tree

Before showing any install UI, detect in this order:

1. Already installed? → matchMedia('(display-mode: standalone)').matches or navigator.standalone. If yes, show nothing.
2. beforeinstallprompt firing? → Chrome / Edge / Android. Show a site install button.
3. iOS Safari? → 'standalone' in navigator and not standalone. Show the illustrated Share hint.
4. Chrome or Firefox on iOS? → One-liner "Open in Safari to install."
5. Safari on macOS? → Tip card in Settings: "File → Add to Dock."
6. Otherwise (Firefox desktop/Android) → Hide the install surface entirely.

The iOS pattern — an illustrated share-sheet hint

iOS is the hardest case and the most important. Since there's no prompt API, the site has to teach the user the three-tap gesture. The canonical approach: a small bottom-sheet that appears on the second visit, or right after a meaningful event like creating an annotation, showing the Share glyph and pointing at where to find it in the toolbar.

A critical detail: on iPhone (iOS 15+) the Share button is in the bottom toolbar; on iPad it's top-right. The arrow in the hint should point accordingly. Detect with a pointer + viewport check, not UA.

The Android / desktop Chrome pattern — a first-class install button

Where beforeinstallprompt works, the pattern is well-established:

1. Listen for the event, call preventDefault(), stash it.
2. Reveal a site-placed "Install Tolstoy" button — in Settings, or as a contextual card right after the user taps "Make available offline."
3. On click, call event.prompt(). The browser shows its own native dialog.
4. Listen for appinstalled and hide the button.

The desktop Safari pattern — a static tip card

Safari macOS has "Add to Dock" from the File menu since Sonoma (2023), but no API. The site's only move is a small static tip card in Settings or after high engagement.

Copy that works

The word install triggers App Store expectations on iOS. Avoid it. Apple's own verb is "Add to Home Screen" — use theirs.

Timing — earn the ask

Never show on first visit. Always wait for a meaningful engagement signal. For a reader, good triggers are ranked:

1. The user just created data worth losing. First annotation made, first work tapped "Make available offline." This is the strongest pitch — "We just saved this on your device. Would you like to make sure it stays?"
2. Second session (user returned voluntarily).
3. More than 60 s of reading in the current session.
4. More than 50% scroll through a chapter.

Defer to requestIdleCallback so the hint never competes with reading.

Dismissal and frequency

• Explicit close button, 44×44 px minimum (WCAG 2.5.5 AAA).
• Persist dismissal with timestamp and count in localStorage.
• Re-surface only after 90 days and another high-signal event.
• Lifetime cap: 3 impressions. Keep a permanent "Install help" link in Settings so users who change their mind can find it.
• On appinstalled or standalone-mode detection, clear dismissal state and never prompt again.

In-app browsers

A user tapping a tolstoy.life link from Twitter, Gmail, Facebook, or Instagram lands in a WKWebView that has no Add to Home Screen in its share sheet. Detect the missing standalone property or absent beforeinstallprompt, and show one line: "Open this page in Safari to install." Never show the full illustrated hint — it'll only frustrate them.

Recommendation for tolstoy.life

Headline copy for that trigger, specific to the project's voice:

Your note is saved here. Add Tolstoy to your Home Screen so it stays — even if you don't visit for a while.

Honest, mechanism-explaining, and aligned with the values check in the README: it honours the reader's device as a resource.

Part 4What sync should feel like

Once two devices are paired, what does the user actually experience when edits made on the phone appear on the laptop? The spec is notably quiet about this. It says "show appropriate UI, but never block the user" — and stops. The design is left as an exercise.

The right answer is a specific kind of calm. Not silent, but close. Not chatty, not at all.

The guiding principle

Mature sync apps converge on this shape. Apple Notes, Obsidian Sync, iA Writer, Linear — none of them announce that sync is happening. They just let the updates appear, the way paper pages let ink appear: without ceremony. The app should feel like it remembered where you left off, because it did.

Six states, six treatments

The fact that conflicts are visible is what lets everything else be invisible. If the user trusts that the app will tell them when a decision is needed, they can trust its silence the rest of the time.

The sync indicator

One small glyph, tucked into the settings corner or next to the work title. No text unless the user asks for it. Each state has a distinct shape, not just a distinct colour — so the indicator remains legible for colour-blind readers and in any ambient lighting where tinted dots would fade into the paper-coloured background. Two of the five states animate (spin for active sync, pulse for demand), adding a third channel that works without colour perception at all.

The welcome-back toast

When the laptop opens and there are fresh edits from the phone, a thin pill appears — briefly, once, never mid-reading:

Auto-dismisses in about 2 seconds. No actions, no "OK" button. The user doesn't need to acknowledge that sync happened — it's not an event, it's the default state of reality. If they missed the toast, the edits are still there.

Whether to ship this toast at all is a judgement call. Apple Notes doesn't — updates just appear. Raindrop and Notion do. Argument for: it builds trust, especially early on. Argument against: a reader shouldn't have to acknowledge their own library. My recommendation: ship it, make it dismissable-forever in settings after the first time ("Got it, don't remind me again"), and let the reader opt out once they trust the system.

What lives in Settings instead

For users who want the detail, the Settings → Sync panel has everything:

Last synced 2 minutes ago · 3 devices · 247 annotations
iPhone · paired March 2026
Work laptop · paired April 2026
Home iPad · paired April 2026
End-to-end encryption: on

Exposed on demand, never pushed. The dot in the corner is the tip of the iceberg; this is the rest.

Why it matters

An e-reader for Tolstoy is not Slack. It doesn't need to feel alive, or present, or eager to talk. It needs to feel like a book that happens to remember where you left it. Every pixel of sync chrome on the screen is a pixel not giving itself to the text.

The architecture has made this easy to honour: the CRDT reconciles without asking anyone's permission, the sync key is already on the laptop, the annotations are already in IndexedDB. The UI can stay out of the way because the system is doing its job underneath. Calm by default is not laziness — it's trust in the design.

There's one hard dependency on the fixes in Part 6: the "loud only on conflict" treatment only works if conflicts are actually rare. Right now, with the §2.3/§8 shape inconsistency and the Y.Array-of-plain-objects duplication bug, concurrent edits can produce silent duplicates and losses — which is the worst of both worlds (the user sees no banner, but their data is gone). Resolving those before Stage 4 ships is what lets this UX be honest.

Part 5Will the corpus volume be manageable?

What's actually fine

• Text-only full-scope downloads (~2.5 GB): 500+ translated works + 90 Jubilee volumes + 10K letters + full wiki + wiki-previews fit comfortably inside Chrome/Firefox/Safari desktop quotas (which are tens of GB in 2026).
• Individual work downloads: War and Peace as served HTML is ~4–8 MB. Nothing scary there.
• Cache API at 26,500 entries: fine for reads. Bulk-writing the whole wiki needs chunking + yielding to the event loop, but that's a coding note, not an architectural problem.
• Y.Doc size for realistic users: 5–15 MB encoded for a power user with 10K annotations. IndexedDB handles that easily.

Real volume risks

1. iOS Safari 7-day eviction. If a user reads in Safari without adding the site to their home screen, iOS will wipe their downloads after 7 days of non-use — even with navigator.storage.persist() granted. The "train reader" user story breaks on iOS unless the user installed to home screen first. The docs say "never block features behind install" which collides with this. Recommendation: elevate install-before-download to a strong prompt on iOS.
2. works.json busts its budget by 30×. The design targets ≤100 KB. At full scope (~10,000 letters indexed as works per the schema) it becomes ~3 MB unminified. Fix: split into works.json / letters.json / volumes.json, or group letters into letter-volume works.
3. Versioned work caches leak. Stage-1 §4.2 says "old cache stays intact until the user explicitly migrates" — but users don't migrate. A user who updates War and Peace twice keeps 3 × 8 MB = 24 MB per work. Across 500 downloaded works that's 12 GB of stale cached versions with no prune. Fix: auto-prune non-current versions after N days unless annotations still reference them.
4. Wiki-previews bundle at ~3 MB gzipped. The docs hand-wave "lazy-load if it gets large." It already is large at full scope. Make lazy-load the default.
5. Prior-version artifacts have no durable home. Tl-pipeline §3.4 says current + 2 prior versions are served, but the versioned subtrees live only in the build output. Netlify build cache is best-effort. If the cache is wiped, annotations anchored to v2024-01-01 silently 404 until someone rebuilds from the right git tag.

Part 6Could there be problems with the QR sync model?

3A · Pairing protocol weaknesses

1. Device re-registration defeats revocation. §4.7 says "revocation is immediate." But the relay authorizes any did whose HMAC is valid — and HMAC validity requires the sync key, which a stolen or compromised device still has. A thief's phone, after "revocation," can simply mint a new did and re-register. Revocation without key rotation is a placebo. Fix: require new-device registration to be signed by an already-authorized device, and make the "stolen device" UI force a key rotation.
2. Confirmation UI can't distinguish attacker from real device. §6.1 step 5 says the two devices exchange a confirmation "so an attacker who somehow obtained the QR can't silently pair." But if the attacker wins the race to the relay, the user simply clicks "yes that's my new phone" on the attacker's connection. Fix: use a Short Authentication String (SAS) — a 4–6 digit code derived post-key-exchange and shown on both devices. The user compares them visually, like Signal does. Without SAS, the confirmation is theater.
3. Same key used for HMAC and AES-GCM. §4.3.1 encrypts with "the sync key"; §4.3 HMACs with "the sync key." That's a textbook crypto footgun — key-separation failure. Fix: HKDF the root key into K_hmac, K_aead, K_export with explicit labels.
4. iCloud Tabs may replicate the pairing URL fragment. If the QR is scanned into Safari (not the installed PWA), the URL including the fragment (containing the key) ends up in Safari history, which iCloud syncs to other Apple devices. Fix: (a) history.replaceState on /pair load to drop the fragment from the URL bar before iCloud sees it; (b) switch to a short opaque token that the PWA exchanges for the real key via a short-lived Worker endpoint.
5. BarcodeDetector is NOT in Safari or iOS. The docs treat it as "default, BIP-39 as fallback." Reality: BIP-39 must be primary on iOS (which is the most security-sensitive path because of #4). The docs need a straight correction and a bundled local QR decoder (jsQR/zxing-wasm) — never a hosted decoder, since that would funnel the key through a third party.
6. Rate-limiting on pairing attempts is assumed, never specced. The BIP-39 66-bit entropy is safe only if the token is burned after first use and attempts are rate-limited at the Durable Object. Neither is in the spec.
7. Key rotation vs stale sync-key backup. User exports key to 1Password, rotates key 6 months later → the exported backup is now useless. The rotation flow must force re-export before completing.

3B · CRDT / Yjs semantic problems

These aren't attacks — they're silent data-loss modes from concurrent edits.

8. Same-note concurrent edit silently loses data. §2.3 says "plain replacement, one wins, history preserves the other." But Y.Map LWW resolves by (clientID, clock), not wall-clock — and there's no UI surfacing the loser. User edits on phone at 09:00, edits the same note differently on laptop at 09:30, both offline; on sync, the phone version may win because its clientID is higher. Laptop text disappears silently.
9. §2.3 and §8 contradict each other. §2.3 specs body as a Y.Array of plain objects. Decision log §8 item 1 says body is Y.Text. These produce different semantics. Pick one before implementation.
10. Y.Array of plain objects produces duplicates on concurrent replace. Replacing a body via delete(0); insert(0, newBody) on two devices ends up with both bodies in the array (Yjs inserts resolve deterministically but don't dedup). Use Y.Text or a single Y.Map key set, not a Y.Array.
11. Delete semantics are undefined. Delete-vs-concurrent-edit can either resurrect a "deleted" annotation with a fresh body or silently discard the edit. Spec must choose. Recommendation: soft-delete with grace window + UI for resurrect/discard choice.
12. Version-migration mutates annotations in place. When a work ships v2 and device A auto-migrates 100 annotations' selectors, device B (offline on v1) later receives those updates pointing at offsets that don't match B's text. Annotations corrupt on B. Fix: migration creates new annotations linked via migratedFrom; old ones stay untouched.
13. Reading-position update rate. Every few seconds → ~65,000 ops/year/work, each sent over the WebSocket. Huge bandwidth and history-bloat cost for a field that's one timestamp + one position. Either debounce aggressively (~30 s), or move reading position out of the Y.Doc into a tiny dedicated LWW endpoint.
14. "Relay never parses" contradicts "merged Yjs state." §4.5 says the relay keeps a compacted merged blob. Compaction via Y.mergeUpdates requires parsing the Yjs framing — and if encryption-at-rest is on, the server can't merge at all. This is an architectural contradiction the spec needs to resolve (probably: with encryption on, only clients compact; server appends until a trusted client uploads a replacement).
15. Two-year dormant user loses everything. Relay prunes rooms at 180 days. iOS may evict IDB. Yjs major version could shift. User loses annotations without warning. Fix: heartbeat from any device keeps room alive; warn user when any paired device has been silent 120 days; require storage.persist() prompt on first annotation.

3C · Platform assumptions that don't hold on iOS

• Installed-PWA URL handler for /pair (handle_links): not supported on iOS Safari.
• Service worker cache-first matcher doing async IDB lookup: risks races with cold-start navigations on iOS. Preload the downloaded-works keyset into an in-SW Set.
• getUserMedia in standalone-mode PWAs was broken until iOS 17.4.
• StorageManager.estimate() under-counts Cache API on iOS 17.x — quota warnings can lie.

Part 7The nastiest finding: a build-pipeline cascade bug

This one isn't about sync or volume — it's in the build. I'm flagging it because it's the single most damaging issue found and it hits the foundation Stage 1 sits on.

The wikiPreviewsUrl field is embedded in every work's manifest.json. When a single wiki article is edited:

1. generate-wiki-previews.py emits a new wiki-previews-v<new-hash>.json
2. generate-asset-manifests.py writes that URL into every work's manifest.json
3. Every work's manifest.json bytes change
4. If manifest.json is included in the work's hashed asset set (and §6.2's walk_files(work_dir) doesn't exclude it), every work gets a new version tag
5. Retention window (current + 2 prior) collapses to "all versions are new" after two wiki edits
6. Every client re-downloads every work on every wiki edit

Compounded by the fact that wiki-integration.md §2.2 and tl-pipeline-integration.md §4.3 specify different shapes for relatedWiki (one with per-article sha256, one with just slug strings). If the richer shape wins, any wiki article edit directly propagates a new hash into every work's manifest regardless of whether manifest.json is itself in the hash.

Also: git_first_commit_date_for_dir doesn't work on shallow Netlify clones. Netlify defaults to --depth=1. Either force full history, or drop the git dependency and store contentDate in the previous works.json as the authoritative value, only advancing it when the content hash changes.

Part 8Hosting — where does all this run?

Two hosting surfaces matter: the static origin (tolstoy.life — serves works, wiki, manifests, app shell) and the sync relay (wss://sync.tolstoy.life — the tiny Cloudflare Worker that ferries annotation blobs between devices). They have very different profiles and different best-fit providers.

The two surfaces

Static origin — options ranked

Ruled out: Vercel (Image Optimization defaults on, which destroys the SHA-256 manifest hashes the PWA relies on — and the $150/TB overage is unworkable for public-domain texts). GitHub Pages (100 GB/month soft limit, no per-path Cache-Control, no Service-Worker-Allowed customisation).

The most interesting free option: Cloudflare Pages has unlimited bandwidth on its free tier, no asset auto-transform, and _headers + Workers for dynamic rewrites. At 10 TB/month that's a $5,000/month delta vs. Netlify's legacy pricing. The main downsides are platform dependency (CF is a hyperscaler) and a 25 MB per-file / 20,000-file project limit (currently not a concern; might bite after Phase 5).

The values-maximalist stack: Bunny.net edge caching in front of Hetzner + Caddy. Bunny is an independent Slovenian CDN with transparent per-GB pricing (~$5/TB) and no AI ambitions. Hetzner is a German-owned VPS provider. Fully portable; no lock-in on the data (it's files on disk, not in a proprietary system).

If you're on a legacy Netlify free plan

Netlify changed its pricing model on 4 September 2025. Accounts created before that date are grandfathered indefinitely onto the legacy plan — "no action is required of you" per Netlify's own docs. The practical difference is substantial:

A grandfathered legacy free plan has ~6.7× the bandwidth of a new free plan — a small asset worth preserving. Two rules follow:

• Don't click any "migrate to new pricing" button in the Netlify dashboard. The switch is permanent and irreversible per Netlify's docs — a one-way door.
• Sign up for a Cloudflare Pages account today anyway. Free, zero commitment. Set up a parallel deploy target from the tolstoylife/website repo — verify the build works and _headers translate cleanly. This turns the eventual migration into a DNS flip, not a project.
• Set bandwidth alerts at 50 GB and 80 GB/month. The legacy free plan hard-stops at 100 GB — not a graceful degrade, just a 402.

Build-minute economics

Bandwidth is one of two budgets the free plan imposes. The other is 300 build minutes per month, and it's the sleeper bottleneck — fine today, structurally dangerous by Phase 3 unless you plan for it. A Phase 5 build that takes ten minutes burns 30 builds per month on the free tier. At three deploys a day, that's five times over budget.

Where the build time goes

An Eleventy + Layer-1 Python build at full scope has four cost centres:

1. npm install — 30–60 s uncached, 5–10 s with Netlify's build cache warm. Essentially free once the cache settles.
2. Eleventy rendering — scales linearly with page count. Roughly 5 ms per page on cold render in Node 20+.
3. Python Layer-1 generators — generate-wiki-previews.py (cheap), generate-related-wiki.py (parses every chapter for wikilinks), generate-asset-manifests.py (the expensive one — SHA-256 of every served file), generate-works-index.py (cheap).
4. PostCSS / Tailwind — 5–15 s, fixed cost, unaffected by content scale.

Realistic projections

"With caching" assumes: npm cache warm, Eleventy's .cache/ persisted, and — critically — the SHA-256 generator caches its output keyed by (mtime, size) so unchanged files aren't re-hashed. Without these, Phase 5 builds easily exceed ten minutes and blow through the budget with room to spare.

The highest-leverage optimisation: cache file hashes

At full scope, the asset-manifest generator will SHA-256 maybe 100,000 served files per build. Hashing 100,000 HTML files (~30 KB each) on Netlify's build hardware is on the order of 3–5 minutes of pure CPU — and almost all of it is redundant, because between two consecutive builds, perhaps 5 files actually changed.

# generate-asset-manifests.py — cached-hash pattern
cache = load_json(".cache/file-hashes.json")  # { path: {mtime, size, sha256} }
for path in walk_files(build_root):
    stat = path.stat()
    cached = cache.get(str(path))
    if cached and cached["mtime"] == stat.st_mtime and cached["size"] == stat.st_size:
        sha = cached["sha256"]  # reuse
    else:
        sha = sha256(path.read_bytes())
        cache[str(path)] = {
            "mtime": stat.st_mtime,
            "size": stat.st_size,
            "sha256": sha,
        }
save_json(".cache/file-hashes.json", cache)

With .cache/ persisted via Netlify's build cache (configure in netlify.toml), this turns Phase 5 builds from 10+ minutes into 2–3 minutes. Do this before Phase 3 ingestion starts — retrofitting is fine, but the determinism CI test I recommended in Part 7 is the natural place to validate that cached-hash output matches from-scratch-hash output byte-for-byte.

The second-highest-leverage optimisation: build-ignore

Netlify supports a build.ignore command that short-circuits the build if a predicate returns zero. Add to netlify.toml:

[build]
  ignore = "git diff --quiet HEAD^ HEAD -- website/"

This skips the build entirely if the last commit didn't touch website/. Root-level doc changes, _generated/ updates, tool-project changes — none of them trigger a build. Realistically this alone eliminates 30–50% of builds for an active project.

Other optimisations, ranked

1. Eleventy incremental mode. eleventy --incremental only re-renders changed pages. Works well in dev; in CI the cache has to be persisted for it to help. Non-trivial to wire correctly but worth 40–60% of full-build time at Phase 5.
2. Per-context build commands. Deploy previews for PRs can skip the Layer-1 pass entirely, using last-good works.json + manifest.json from the main branch. The preview is visually complete; only the PWA offline-download contract is stale. Acceptable for review builds.
3. Split deploys. If facsimile scans are their own Netlify site (scans.tolstoy.life), they don't factor into the main tolstoy.life build at all. Scan updates deploy independently on their own cadence.
4. Nightly-only full builds via scheduled webhook. Keep PR / commit builds fast (skip the heavy Layer-1 pass); run a 15-minute full rebuild once a day via a Netlify scheduled build. Trade-off: versioned manifests lag commits by up to 24 hours.
5. Move the whole build to GitHub Actions and netlify deploy --prod the result. GitHub Actions free tier gives 2,000 min/month for public repos — 6.7× more than Netlify's 300. tolstoylife/website is likely public. Netlify then serves a pre-built directory; it's not running the build itself.

Option 5 is the nuclear escape hatch — if Netlify's 300 min becomes structurally inadequate, moving the build to Actions while keeping Netlify as pure hosting preserves the 100 GB legacy bandwidth allowance without the build-minute pressure. A genuinely portable architecture in two places at once.

When to act

Static origin — the minimum-change fix (do this now)

Before migrating anything, fix the determinism issue flagged in Part 7 on Netlify itself. Asset Optimization ("post-processing") can be fully disabled without leaving the platform. Add a netlify.toml:

[build]
  publish = "_site"
  command = "npm run build"

[build.environment]
  PYTHON_VERSION = "3.11.9"
  TZ = "UTC"
  LC_ALL = "C.UTF-8"

[build.processing]
  skip_processing = true
[build.processing.css]
  bundle = false
  minify = false
[build.processing.js]
  bundle = false
  minify = false
[build.processing.html]
  pretty_urls = false
[build.processing.images]
  compress = false

Then add _headers:

/works.json
  Cache-Control: public, max-age=300, must-revalidate

/*/manifest.json
  Cache-Control: public, max-age=300, must-revalidate

/*/v*/*
  Cache-Control: public, max-age=31536000, immutable

/wiki-previews-v*.json
  Cache-Control: public, max-age=31536000, immutable

/sw.js
  Cache-Control: no-cache
  Service-Worker-Allowed: /

Re-run the determinism CI (build twice, diff). The audit should now pass.

Migration trigger: move to Cloudflare Pages when bandwidth approaches the plan's hard limit — 80 GB/month on a legacy free plan (100 GB cap), ~500 GB/month on a legacy Pro plan, or whenever Netlify's post-September-2025 credit-based pricing would apply to a new account.

Sync relay — Cloudflare Workers + Durable Objects

The architecture doc picks CF Workers + Durable Objects with hibernatable WebSockets. Research confirms this is the right default. Key correction to the doc's §7: the "fits in the free tier" claim is aspirational. Hibernatable WebSockets + DO storage require Workers Paid ($5/month). That's the real floor.

Cost projections at realistic scale:

At every tier above, the sync relay is cheap. The main risks are not cost — they're operational.

Combined monthly cost picture

The static-origin bandwidth is the dominant cost driver at scale, not the sync relay. This is why the migration path off Netlify matters even though everything fits comfortably on the free tier today.

Operational action items

If the project stays on Cloudflare Workers + DO for the sync relay (recommended):

1. Upgrade to Workers Paid at launch. Document the $5/mo floor; update yjs-schema-and-sync.md §7 to replace "fits in the free tier" with concrete figures.
2. Pin the Durable Object location to EU. On first idFromName() call, pass { locationHint: "weur" }. Swedish users' blobs stay in Western-European data centres (Amsterdam, Frankfurt, Dublin). Disclose this in the privacy settings panel.
3. Vendor the y-durableobjects implementation. It's a small-maintainer project. Fork into tolstoylife/y-durableobjects, audit, pin to a reviewed commit. Don't depend on an unmaintained npm tag.
4. Write the Hocuspocus-on-Fly fallback now. A 50-line Dockerfile + fly.toml committed to the repo (not deployed) operationalises the "operator can be swapped without users noticing" promise. Without it, that promise is aspirational.
5. Nightly R2 backup of DO state. DO storage is durable but has no external backup. A DO Alarm that exports each active room to R2 (CF's object store, $0.015/GB-month, no egress fees) is cheap insurance — ~$0.30/month at 100K users. It also becomes the migration-off-CF pathway.
6. Measure four metrics from day one: DO requests/day, P95 cold-start on first connect after idle, snapshot size distribution per room, rooms-flagged-for-pruning count.
7. Abuse protection. CF WAF rules: rate-limit WebSocket upgrades per-IP to ~10/minute. Reject connections without a well-formed HMAC param inside the Worker (never wakes the DO). Per-room message-rate cap in the DO itself to prevent a malicious device flooding its own room.

LightRAG — the third surface, internal only

Beyond the two public-facing surfaces is a third that never touches the public internet: the LightRAG indexing box that runs the nightly semantic-search pipeline (Layer 2 in the scaled architecture — see the project CLAUDE.md). It's a developer tool, not user-facing. Every design decision should fall out of that fact.

LightRAG has two computational phases:

1. Embedding generation — small model (e.g. nomic-embed-text, ~275 MB). CPU-fast. Cheap.
2. LLM extraction — entity, relationship, and summary extraction via Qwen2.5:7b or similar. This is where most of the compute goes.

Plus graph and vector storage (NetworkX + NanoVectorDB), which are tiny and purely disk-bound.

The real question is whether a VPS can run Qwen2.5:7b efficiently enough. The answer splits into two regimes.

CPU-only — Hetzner standard VPS

Qwen2.5:7b at Q4_K_M quantisation needs ~5–6 GB RAM to run, ~8–12 GB with a 32K context. Throughput on modern Xeon / EPYC cores is 5–15 tokens per second.

CCX33 handles the nightly incremental easily. After initial ingestion, you're looking at perhaps 10–100 changed files per day in steady state — minutes of work at 10 tokens/second.

The catch is the initial full ingestion. 26,500 files × multiple LLM calls per chunk can mean a week of continuous compute on a CPU-only box. Doable if you're patient, annoying if you're not.

The GPU shortcut

Hetzner added dedicated GPU servers in 2024. GEX44 with an RTX 4000 SFF Ada (20 GB VRAM) at ~€184/month makes Qwen2.5:7b run at 40+ tokens per second — initial ingestion shrinks from a week to hours. Overkill for ongoing incremental sync, though.

Better split: do the initial ingestion on a rented-by-the-hour GPU (RunPod or Vast.ai — roughly $0.30–$0.60/hour for an A5000 or RTX 4090), then move the resulting index to the CPU VPS for ongoing incremental work. One-time cost: ~$20–$50. Ongoing cost: €24/month.

Recommended setup

1. Keep local dev primary. An Apple Silicon Mac runs Ollama via Metal at 40+ tokens/sec — essentially free, no monthly cost. Use it for development and test ingestions.
2. Rent a GPU by the hour once for the first full Tolstoy ingestion (~$30 on RunPod). Save the resulting lightrag/data/ directory.
3. Hetzner CCX33 (~€24/month) hosts the nightly sync and the HTTP query API (port 8420). Reach it via Tailscale or WireGuard — never expose the query API publicly.
4. Back up lightrag/data/ to Hetzner Storage Box or Cloudflare R2 weekly. The index is regenerable from the vault, but a fresh regen costs hours, so keeping the artefact is worth the near-zero storage cost.

The critical separation

LightRAG holds the whole extraction-pipeline state — the knowledge graph, the vector index, the raw LLM-extracted entities. It's a developer tool that happens to be an HTTP service. Keeping it off the public internet is cheaper (no CDN, no TLS concerns, no WAF rules), safer (no attack surface), and matches how it's actually used: by Claude sessions during ingestion and lint, not by readers.

A note on sovereignty and lock-in

The project's stated values include independence from platform gatekeepers. Hosting is the place this value is actually tested. Worth being honest:

• Netlify and Cloudflare are both US-headquartered platforms. Neither is "independent" in the Tolstoy sense. They are, however, good technical fits, and the lock-in risk is bounded because the static content is plain files in a git repo — migration is a build-and-push, not a data export.
• The sync relay has higher lock-in. CF Durable Objects has a proprietary API. The protocol (Yjs wire) is portable, so swapping operators means rewriting ~200 lines of TypeScript, not migrating user data. The Hocuspocus fallback makes this concrete.
• True independence is Bunny.net + Hetzner (static) and Hocuspocus on Hetzner (relay). Doable. Costs more ops time. A reasonable Phase 5+ goal; not a reasonable Stage-1 blocker.

The Cloudflare consolidation arc

Having committed to Cloudflare for the domain, the sync relay, and R2 backups, the question of whether the static origin should also move is half-decided. The direction is clear; the open questions are when and how, not whether.

The two-phase architectural evolution

Cloudflare Pages is ideal for the project today. It is not sufficient at Phase 5 scale. The difference isn't bandwidth — it's a per-deployment file cap.

Cloudflare Pages caps each deployment at 20,000 files and 25 MB per file. At Phase 5 the Tolstoy vault projects to 26,500 wiki articles, ~500 translated works with many chapters each, ~10,000 letters, and ~90 Jubilee volumes. The total easily exceeds 100,000 files — five times Pages' limit.

The native Cloudflare answer: Pages + R2

The ranked options table earlier in this section listed R2 + Cloudflare CDN as the "best pure economics at 10+ TB/month" option. At Phase 5 it also becomes the answer to the file-count problem. The split:

• CF Pages serves the app shell, CSS, JavaScript, the wiki-previews bundle, works.json, the per-work manifest.json files, and any small fixed assets. A few hundred files — comfortably under the 20k cap.
• R2 holds the long tail — every chapter file, every wiki article, every letter, every versioned subtree. No file-count limit. Egress-free when served through Cloudflare's CDN.
• A small Worker (~50 lines) routes requests by path: /wiki/* → R2 bucket, /works/*/text/* → R2 bucket, everything else → Pages origin. Sets Cache-Control per path. Optionally verifies the requested SHA-256 against the manifest as an integrity check.

Both deployments stay in the same Cloudflare account. Same dashboard, same billing, same DNS. The manifest.json contract from Part 7 doesn't care where the bytes physically live — the manifest's url field is the origin-relative path, and the Worker resolves it.

Staged migration, no big bang

The parallel CF Pages account you already set up is the right first step. The rest, at your pace:

1. Transfer the domain to Cloudflare Registrar at the next Netlify renewal. Saves ~$22/year and centralises DNS management.
2. Connect tolstoylife/website to CF Pages as a second deploy target for the main branch. Builds produce a pages.dev URL alongside the Netlify deploy. Zero user-facing change yet.
3. Run the cross-platform determinism test: build the same git commit on both Netlify and CF Pages, diff the output directories. They must be byte-identical. If they're not, you've found a bug in either provider's build pipeline before it costs anything. This extends the single-platform determinism CI test from Part 7 into a cross-platform reproducibility test.
4. Flip DNS when satisfied. The A and CNAME records for tolstoy.life point to CF Pages instead of Netlify. Rollback is the same DNS change in reverse — seconds of propagation.
5. Keep Netlify deploying silently as a standby for 6–12 months. Don't formally cancel. If Cloudflare ever has an issue, flip DNS back. The grandfathered 100 GB bandwidth remains a passive hedge. Costs nothing — Netlify free stays free as long as builds stay under 300 min/month.
6. Budget for the R2 split as a Phase 5 milestone. When the file count approaches 15,000 (an alarm, not a cliff), implement the Pages-shell + R2-content split. The Worker router is about a week of work; the Eleventy build-config change to output the split is smaller than it sounds.

Concentration without lock-in

This consolidates significant infrastructure at one US hyperscaler. The project's stated value is "not dependent on big data companies." Cloudflare is a big data company. The mitigation — and it's a real one — is that every piece of the data remains portable:

• R2 is S3-compatible. A single rclone sync moves content to any other object store.
• The sync relay protocol is standard Yjs. Swapping CF Workers for Hocuspocus-on-Hetzner is the ~200-line rewrite already documented as a fallback earlier in this part.
• The static build output is just files in a git repo — deployable anywhere in minutes.
• The domain transfers out in 5 days if Cloudflare Registrar's posture ever changes.

Concentration without lock-in is the honest phrase for this stack. Every piece is portable; the consolidation is operational convenience, not architectural dependency. The Bunny.net + Hetzner stack remains the sovereignty option if the politics ever change — and the migration path above makes arriving there simpler from Cloudflare than from Netlify, because R2 exports cleanly to Bunny Storage and Worker logic ports cleanly to Caddy configuration.

Recommendation

Part 9Priority fixes, ranked

Before Stage 1 ships

1. Fix the wiki-previews/manifest cascade. Exclude cross-references from the work hash. (Pipeline determinism)
2. Reconcile §2.3 vs decision log §8 for annotation body. One shape, one concurrency story. (Data integrity)
3. Publish a deterministic-build CI test. Build twice, diff. Block merges. (Pipeline correctness)
4. Add chapterUri validator + one-shot migration. Uniqueness check across corpus. (Annotation anchoring)
5. Pick a canonical JSON library (rfc8785) and NFC-normalize strings. (Determinism)

Before Stage 4 ships

6. HKDF key separation for HMAC / AEAD / export keys. (Cryptographic hygiene)
7. SAS confirmation handshake replacing yes/no pairing confirm. (Real MITM protection)
8. Device-registration authorization (existing device must sign new-device registration). (Fix the revocation-is-placebo bug)
9. Rotation flow blocks on re-export with stale-backup banner. (Prevent user data loss after positive security action)
10. Rate-limit pairing attempts at the Durable Object, one-use BIP-39 tokens. (Brute-force defense)
11. Resolve the "relay doesn't parse" contradiction. Either spec client-side compaction under encryption, or weaken the claim. (Architectural honesty)
12. BIP-39 as iOS primary, not fallback; bundle local QR decoder. (Platform correctness)
13. iCloud Tabs mitigation — history.replaceState on /pair, Referrer-Policy: no-referrer. (Fragment leak)
14. Dormant-user heartbeat — keep room alive if any paired device is active. (2-year lifecycle)

Broader

15. Split works.json by type once letters are indexed. (Volume)
16. Auto-prune stale work-version caches with annotation-reference reachability. (Storage leak)
17. Lazy-load the wiki-previews bundle from day one. (Shell install cost)
18. Move reading-position out of Yjs or throttle it to ~30 s. (Bandwidth + bloat)
19. Version-migration creates new annotations, doesn't mutate old ones. (Multi-device correctness)

Part 10Overall verdict

The architecture is fundamentally sound — the design instincts (opaque-blob relay, no accounts, content-addressed versioning, W3C annotations, public-domain-aligned values) are all correct. The docs are unusually honest about their own threat model (the §4.3.1 cryptography callout is exemplary).

The weaknesses are specification-gap failures, not architectural rot. A two-page "sync security spec" locking down HKDF labels, SAS protocol, rate-limit numbers, device-registration authorization, and rotation-export atomicity would close most of the sync risks. A week of pipeline hardening (excluding cross-references from hashes, the determinism CI test, a canonical JSON encoder) would close most of the build risks.

Volume is manageable for the realistic user. Sync is workable with the fixes above. The project can ship.

The single most important thing is to treat the PWA docs as drafts that assume a happy path, and run the priority-fix list before implementation begins. Every issue in this report is findable only because the docs are thorough enough to have specified the details — which is the opposite of the usual problem.