Offline

Balqalam targets schools where 2G/3G fallback, intermittent WiFi, and full outages are the norm — Sudan pilots, rural transit routes, exam halls in basements, applicants on prepaid mobile data. This page is the platform-wide strategy for delivering a production-grade offline engine with a no-compromise foundation, then layering per-role features in phases on top of that solid base.

We do not ship half-measures. The foundation is built once and built right; per-role features layer on top in phases. For tenancy and sync constraints see Multi-tenancy and Database. For prior-art epic shape this doc follows see Document Intelligence. For dictionary-key conventions see Translation.

Why this matters

Today the platform handles network failure in scattered, feature-specific ways. The pain points compound during the moments that matter most.

The platform serves ~12 K students across 8 active schools today; the Sudan and KSA pilot targets push that to ~40 K within 12 months. Sudan's mobile carriers average 1.2 Mbps downlink with frequent dropouts; KSA boarding schools see exam-hall-WiFi saturation during high-stakes weeks. A solid offline engine is the unblock for both deployments.

What success looks like

These are the headline metrics the team commits to at "Foundation gate passed" + "all per-role epics shipped".

1. Zero attendance loss on disconnect — 100% of teacher attendance batches recorded within 60 s of reconnect.
2. Zero exam-submit loss — 100% of submitExamSession calls eventually complete, even after browser restart.
3. Sub-1 s offline load for timetable + announcements after initial visit (instant render from Dexie live query).
4. PWA install rate ≥ 35% on mobile for active teachers within 4 weeks of rollout.
5. Sync success rate ≥ 99.9% across all queued mutations (rolling 7-day window).
6. Storage usage ≤ 25 MB per active user on average (Safari iOS quota headroom).
7. Bundle size delta — foundation chunk ≤ 35 KB gzipped; per-epic chunks lazy-loaded.
8. Main thread budget — sync flush never blocks the main thread > 16 ms (work moves to Web Worker).
9. First-byte cache invalidation — server WebSocket push invalidates client cache within 200 ms of remote write.

Shipped 2026-08-29/30 — the outbox, and a policy

The first slice of this plan is live, scoped to Lumos lessons: an outbox (src/lib/offline/outbox.ts, IndexedDB) queues playback position, completion, quiz answers and assignment text for POST /api/offline/sync, which is idempotent per item and answers a verdict per item; rejections park visibly on /offline with retry/discard — so the "pending sync visibility" row above is ✓ for lessons and still ✗ for the other actions. A download-for-offline slice (video + materials on the device) shipped on 08-29 and was withdrawn on 08-30 by school policy: videos and materials are viewed in the app, never copied to a device, and IndexedDB v2 drops any media a device had stored. The service worker (public/service-worker.js, v2) now actually installs.

Shipped 2026-09-12 — installable, and attendance in the outbox

The PWA layer was repaired after a live audit of demo and kingfahd: the manifest is now per-tenant (school name, Arabic RTL by default, the school's brand colour), the missing icons exist, and service worker v3 precaches /ar/offline and /en/offline instead of two redirects — so the offline fallback works for the first time — and no longer caches authenticated pages or API bodies. Quick attendance is the first non-lesson outbox kind: a mark made offline is saved on the phone and replayed through the same ownership check and markAttendance path when the connection returns; a newer mark already on the server wins. The "Teacher marking attendance offline" row above is now ✓. Verify any host with kun's pwa-audit script.

Two more pieces landed the same day: Web Push (a browser or the installed app subscribes from the notification preferences page; absence, exam and live-class notices arrive as system notifications and a tap opens the school's own route) and an install card on phone-sized dashboards that offers "Add to Home Screen" (Android shows the real install prompt; iPhone gets the Share → Add to Home Screen hint).

How to experience it (any school, today)

1. Install. On Android Chrome open https://<school>.balqalam.com, sign in, and a welcome sheet slides up offering the app — tap Continue: Android opens the install sheet; iPhone opens the share sheet, where you pick Add to Home Screen (a two-step guide appears underneath). The icon carries the school's name in Arabic, opens right-to-left in the school's colour, and has no browser chrome.
2. Mark attendance offline. Open Attendance → Quick for a section, put the phone in airplane mode, mark the absentees and save. The panel says the marks were saved on the device and the sync banner shows one pending item. Turn the network back on: the banner drains within seconds and the marks appear on the server; save the same section again and the server keeps whichever mark is newer. Guardians get the absence notice when the replay lands, not before.
3. Turn on push. Notifications → Preferences → Push asks the browser's permission on the tap and subscribes this device. From then on an absence, exam or live-class notice also arrives as a system notification; tapping it opens that page in the installed app. On iPhone the toggle only works from the installed app (Safari cannot receive Web Push).
4. Lose the connection anywhere. In airplane mode, opening any app route shows the school's offline page in the right language — with the outbox view listing what is queued — instead of the browser's error screen.

What is verified by tooling: the install audit passes on demo and kingfahd (0 FAIL), the worker controls the page after one reload, the outbox replay returns applied then duplicate, and the push cron reports the channel configured. What only a phone can verify: that a push actually shows on a device and that the offline page appears under a real disconnect — both tracked in hogwarts#408.

Shipped 2026-09-13/14 — explorable offline, and fast on thin networks

A live measurement of kingfahd on 4G explained the slow menu. Every dashboard open shipped 1.38 MB of HTML, 935 KB of it the dictionary, plus 63 script chunks, 1 MB of CSS from marketing-site clones, 36 prefetch requests and two 1.1 MB Server Action responses. The proxy wrote the locale cookie on every response, and Next answers any Server Action whose request carries a proxy-set cookie with a full re-render of the page. No static file was cached at Cloudflare's edge either: each chunk round-tripped to the single container, about 0.5 s apiece from Europe.

What changed for speed:

• The locale cookie is written only when it changes, so a Server Action answers with its own data again.
• The Worker serves hashed chunks, fonts, icons and optimised images from Cloudflare's edge. It asks the container for uncompressed bytes and lets the edge compress for each visitor, keys optimised images by the format the browser accepts, and stamps every static response x-edge-cache: hit | miss | bypass.
• The clone stylesheets load only on the pages that use them.
• Every sidebar route has a loading boundary, so its link is prefetched and a tap draws the skeleton at once. Pages visited in the last 30 s come back from memory.
• The header's messages link prefetches on hover, touch or focus, not on sight: its route group carried a 684 KB dictionary.
• The notification bell backs off for 15 s after a failed request. With the server unreachable it had been sending bursts of about 120 requests.

How offline works now (service worker v7):

• Saved per person. Every screen a signed-in user opens is kept in a cache named by a per-user session key the server sends with each response. A response carrying a different key, or none, empties the previous person's pages. The sign-out button, and the sign-in and join pages as they open, tell the worker to forget everything first: on a slow network a saved copy can appear before any response reveals who is signed in.
• Saved as whole pages. A client-side navigation leaves no HTML behind, so each dashboard page opened on a good connection (4G-class, data saver off) is also saved as a full page, once a day. The installed app also saves the whole sidebar once a day. A navigation's payload is saved too, but it only answers the exact navigation it came from.
• Network first. A page with a saved copy shows it when the network fails, or has not answered within four seconds, and the request keeps running to refresh the copy. It does so silently: no strip, no toast, no "offline", "slow" or "back online" notice (#416). When the connection comes back, a page showing its saved copy refreshes itself, and queued work drains on its own. The only strip left is work the server rejected — "N items need attention", linking to /offline.
• Unopened pages say so. A page with no saved copy shows "This page isn't on this device yet" with Back and Retry; an installed iPhone app has no back button of its own. The offline page and the files it needs live in their own cache, refreshed daily, so the fallback survives deploys.
• Lessons open offline; their videos do not. A saved lesson page holds text, quiz questions (never the answers) and a reference to the video — never the video, a recording or a material. Those stay behind /api/lumos/*, which the worker never caches, and the video address refuses anything but the in-app player. This is the 2026-08-30 school policy (videos and materials are watched in the app, never copied to a device), and it is why a PRIVATE video cannot outlive its owner's choice on someone's phone.
• The installed app cannot block screenshots. An installed PWA is still the browser: no web API stops or detects a screen capture. Every video, recording and the live room carry the viewer's code in a 1% watermark that survives a capture, plus a visible mark on capture signals — see Lumos → protection. Real blocking needs a native shell (hogwarts#411).

Corrected on 2026-09-14. The first version of this section passed a test that replayed navigations the same tab had just made. With the server actually stopped, three things failed, and a fourth gap showed on a slow network:

Measured on a local production build — offline checks with the server stopped, slow checks behind a proxy that holds every response for 5 s:

How to experience it

1. Open the app on a good connection, sign in, and open a few sidebar pages.
2. Airplane mode. Tap through the pages you opened: they render as last seen under "You're offline. Pages you've opened before still work…". A page you never opened shows "This page isn't on this device yet", and Back returns to where you were. Anything you mark is queued as before.
3. On a weak signal rather than none, a saved page that takes longer than four seconds shows its saved copy, silently; it refreshes itself when the connection returns.
4. Sign out and sign in as another account on the same phone: nothing the first account saved appears, even before the network answers.

To test from a computer, stop the server, or use a phone in airplane mode. The browser developer tools' Offline setting does not reach the service worker's own requests, so "offline" pages quietly load from the server.

Limits

• Storage. A saved dashboard page is about 1.4 MB, mostly the dictionary. The cap of 80 saved pages per person allows about 110 MB, far past the 25 MB average in What success looks like. Moving the dictionary out of the HTML fixes size and speed together.
• Server load. Saving opened pages costs one extra server render per page, per person, per day.
• Session expiry lands on the sign-in page, which also clears that same person's saved pages.
• Script eviction. Past 400 files the worker's static cache drops its oldest entries first, which can include scripts every page uses; a saved page whose scripts were dropped shows without them offline.
• Delete account signs out without clearing saved pages first; the session-key check clears them as soon as the network answers.

Files

Engineering principles (no compromise)

These are non-negotiable. Each principle drives concrete choices in the architecture.

1. Sync never blocks the main thread. All replay, encryption, compression, and conflict checking run in a dedicated Web Worker (sync-worker.ts). The main thread is reserved for UI.
2. Large blobs go to OPFS, not IDB. Attachments, exam papers, recorded audio, photos all use the Origin Private File System. IDB stores only structured payloads and chunk metadata.
3. Every mutation is tamper-evident. Every envelope carries a SHA-256 content hash. The server verifies on intake; the client verifies on replay.
4. Real-time cache invalidation. WebSocket pushes invalidation events from server to all connected clients. No silent staleness; never wait for refetchOnReconnect.
5. Code-split per epic. Foundation chunk ≤ 35 KB. Each per-role epic ships its own lazy-loaded chunk. New schools download only the foundation; per-feature code loads on first use.
6. Telemetry from day 1. Every state transition (enqueue, flush, conflict, error, retry) emits a structured event to Sentry and to OfflineSyncLog. No retrofitting.
7. Feature flag gates new features, never the foundation. School.offlineMode toggles features; the foundation library is always loaded for installed PWAs. Foundation cannot be partially adopted.
8. Performance budgets are CI gates. size-limit, Lighthouse CI, custom Sentry budgets. CI fails on regression; we never "fix it in a follow-up".
9. Conflict resolution is always explicit to the user. Silent overwrites are forbidden. Every server-rejected mutation surfaces a structured conflict UI with the data on both sides + a resolution choice.
10. The foundation library is versioned. Schema migrations between versions are tested. We never break older PWAs in the wild without a documented upgrade path.
11. Conditions of use are observable. useNetworkStatus, useStorageEstimate, usePendingSyncCount are public hooks. Any feature surface can show users what's happening.
12. Multi-tenant safety is architectural, not procedural. IDB DB name namespaced by schoolId; SW reads tenant from session cookie at fetch time, never from a global; cross-tenant leak is impossible by construction.

Foundation architecture decisions

Each compromise we considered, and why we rejected it.

Scope

10 epics, ~42 stories, 231 story points. EPIC-0 is the foundation that every other epic depends on and must pass the Foundation Gate (see below) before any per-role work starts.

Architecture context

The plan extends existing resilience scaffolding rather than replacing it. Two gold-standard implementations already live in the codebase — the exam auto-save hook and the geofence GPS tracker — and the foundation epic generalizes both into one reusable, production-grade library.

Schema facts

• Every business model has schoolId with @@index([schoolId]). Every offline write MUST preserve this.
• KioskLog.syncedToAttendance already exists at prisma/models/attendance.prisma:404 — currently set synchronously; will be reused as the deferred-sync flag.
• New models required: OfflineMutation (durable server-side queue), OfflineSyncLog (idempotency cache, 30-day TTL), CacheInvalidation (broadcast topic log, 7-day TTL).
• New School.offlineMode enum field: disabled / limited / full. Default limited for new schools, full for pilot rollouts.
• Translation strings live in src/components/internationalization/{school-en,school-ar}.json under dictionary.offline.*.

Patterns

Every epic follows the same conventions.

• Dexie tenant DB. One Dexie database per origin named hogwarts-${schoolId} with versioned schema. Live queries via useLiveQuery. Migrations tested in CI.
• OPFS blobs. Files > 100 KB go to OPFS. IDB stores { opfsPath, size, sha256, mimeType } only.
• Sync worker. sync-worker.ts runs Dexie queries, payload compression, content-hash verification, replay HTTP. Main thread posts messages to it; worker streams progress back.
• Discriminated mutation envelope. { id, schoolId, userId, action, payload, idempotencyKey, contentHash, attempts, lastError, state, createdAt } where action is a string literal resolved via actionRegistry at flush time.
• Idempotency keys. cuid v2 generated client-side; persisted in payload; server checks OfflineSyncLog before re-applying.
• Per-domain sync shards. /api/offline/sync/{attendance|exam|transport|messaging|application} for parallel processing. Each endpoint dispatches to its domain's action handlers.
• WebSocket invalidation. Server broadcasts cache-invalidate messages on writes. Client matches against active Dexie tables and triggers live-query refresh.
• Thin react hooks. Feature code uses useOfflineMutation / useLiveQuery / useNetworkStatus / usePendingSyncCount / useStorageEstimate. Never imports dexie or @tanstack/* directly.
• i18n-first. Every offline string lives in dictionary.offline.*. No hardcoded English in JSX, toasts, or error returns.
• Code-split per epic. Per-feature offline code lives in lazy chunks. import("./feature/offline.ts") boundaries.

Current state vs. target state

Conflict resolution policy per action

The default is server-authoritative with structured merge UI. Per-action overrides below.

Browser compatibility matrix

The strategy targets the browsers schools actually use. Capability detection at runtime in useNetworkStatus and useOPFSSupport.

Where OPFS is missing, the storage layer falls back to IDB blob fields with a quota warning. Where Background Sync is missing, sync runs on online event + visibility change while the tab is open; on PWA reopen the worker drains immediately.

Storage budget per role

navigator.storage.estimate() watchdog warns at 80% utilization. OPFS is included in the same origin quota; we partition deliberately.

Performance budgets

These are the budgets CI enforces.

Pre-foundation phase (Week 0): Spikes & Research

Ten spike tasks ship before EPIC-0 starts. Each is timeboxed to 0.5-1 day and produces a Decision Record. All must merge before EPIC-0 starts — these answer questions the foundation depends on.

Stories per epic

EPIC-0 — Foundation: Production-Grade Offline Engine (62 pts)

The foundation is built once, built right, and ships before any per-role work starts. Five sub-epics, all merged before the Foundation Gate (see below).

0.A — Storage layer (18 pts)

0.B — Sync worker (18 pts)

0.C — Network + conflict primitives (12 pts)

0.D — Service worker as coordinator (8 pts)

0.E — Telemetry + devtools (6 pts)

The foundation epic ships the production-grade offline engine that every per-role epic consumes. New files land under src/lib/offline/{db,opfs,registry,types,state-machine,compression,integrity}.ts, the sync-worker.ts worker, and src/components/offline/{hooks,provider,devtools}/. Blocks every other epic until Foundation Gate is passed.

EPIC-1 — PWA Installability + App-Shell Pre-Cache (15 pts)

Promotes the existing installable manifest into a true PWA. Cache name uses __BUILD_ID__ to invalidate on deploy. Install banner shown on third dashboard visit, dismissal persisted to Dexie. The update flow listens for controllerchange and prompts the user to reload when a new SW is waiting. Staged rollout enables SW updates to 10% → 50% → 100% of devices over 48 h.

EPIC-2 — Smart Read Cache (24 pts)

Read-mostly surfaces (timetable, announcements, profile, roster, dashboard) render instantly offline from Dexie live queries. Cache keys follow [schoolId, resource, id]. Network-aware staleTime derives from performance-optimization.ts thresholds — 5min on 4G, 30min on slow-2g. WebSocket pushes invalidate cached entries within 200 ms of remote writes.

EPIC-3 — Teacher Offline (Attendance + QR + Grading) (32 pts)

Wraps bulkUploadAttendance at src/components/school-dashboard/attendance/actions/bulk.ts:33 as a registered action. Roster pre-cache populates Dexie + OPFS (student photos) when a teacher opens a class. QR scan queue replaces single-try toast at qr-scanner.tsx:209. Mobile swipe-grading batches 25 swipes into one mutation.

EPIC-4 — Student Offline (Exam Submit + Proctor Log) (22 pts)

Closes the critical gap: today auto-save survives connectivity loss but the final submitExamSession at src/components/school-dashboard/exams/take/actions.ts:369 does not. Idempotency key = sessionId. Server rejects submit on paperVersion mismatch with structured conflict UI. Auto-save migration drops ~120 lines of bespoke retry/backoff.

EPIC-5 — Driver Offline (Trip Boarding) (15 pts)

Mirrors the gold-standard geofence pattern into the in-app driver experience. recordBoardingFromGeofenceInternal is already idempotent on (schoolId, tripId, studentId). Pre-cache populates Dexie + OPFS at trip start. Story 5.4 retires the bespoke LocationQueue class at geo-tracker.tsx:59.

EPIC-6 — Applicant Offline (Resumable Attachments + Submit) (18 pts)

Applicants on flaky 3G can resume a 5 MB transcript upload after dropping mid-transfer — chunks live in OPFS. New /api/uploads/resumable/[uploadId]/[partNumber] endpoint tracks completed parts. Application context at application-context.tsx:412 upgrades from localStorage to Dexie for cross-tab consistency.

EPIC-7 — Messaging Outbound Queue (16 pts)

Closes the messaging gap. Bubble states map cleanly onto the XState mutation lifecycle from EPIC-0. WhatsApp bridge receives clientMessageId so duplicate-on-replay is prevented at the bridge layer.

EPIC-8 — Observability + Offline Analytics (14 pts)

Answers "is offline helping users" with hard numbers. Per-school metrics surface in the SaaS dashboard. SLI dashboard exposed to ADMIN role so each school can self-monitor.

EPIC-9 — Docs, i18n, Admin Config (13 pts)

Self-contained delivery epic. Story 9.4 covers all four role flows via Playwright context.setOffline(true). Dictionary keys: online, offline, slowConnection, backOnline, syncing, pendingCount, pendingDrawerTitle, retry, discard, discardConfirm, lastSynced, cached, submissionQueued, submissionInFlight, conflictTitle, conflictBody, conflictResolveKeep, conflictResolveDiscard, conflictResolveMerge, installAvailable, installCta, updateAvailable, updateCta, offlinePageTitle, offlinePageBody, dataSaver, featureUnavailableOffline, storageNearFull, storageFullError, paperVersionConflict, gradingConflict.

Migration strategy

Moving from today's state to production-grade offline happens in three stages per feature. No big-bang switch.

1. Dual-write phase. Feature still writes online directly AND enqueues for offline replay through the new foundation. Server-side OfflineSyncLog dedupes via idempotency key. Detect divergence in telemetry; alert on any.
2. Cutover. Switch the feature to enqueue-first. Online flush is automatic and immediate. Feature flag School.offlineMode='full' enables the queue path; limited keeps online-only.
3. Cleanup. Remove the bespoke retry / localStorage / in-memory queue specific to that feature. Delete dead code in use-auto-save.ts, useOfflineQueue (attendance/shared/hooks.ts:541), LocationQueue (geo-tracker.tsx:59).

Order of feature cutover: Attendance → Exam submit → Driver boarding → Application attachments → Messaging. Each cutover lives behind the feature flag and ships independently.

Cross-cutting

Schema additions

Apply via Neon branch-before-touch protocol (mcp__Neon__create_branch → migrate on branch → mcp__Neon__compare_database_schema → mcp__Neon__complete_database_migration).

• OfflineMutation — durable server-side queue: id, schoolId @@index, userId @@index, action, idempotencyKey @unique, contentHash, payload Json, status enum(PENDING|SUCCESS|FAILED|CONFLICT), attempts, lastError, createdAt, syncedAt.
• OfflineSyncLog — idempotency cache: idempotencyKey @id, schoolId @@index, userId, action, responseJson Json, replayedAt. 30-day TTL job.
• CacheInvalidation — broadcast topic log: id, schoolId @@index, topic, keyHash, emittedAt, propagatedAt. 7-day TTL job.
• School.offlineMode — enum field disabled / limited / full. Default limited.
• KioskLog.syncedToAttendance — already exists. Reuse, do not duplicate.

RBAC

• Pending-sync drawer: visible to all authenticated roles. Each user sees only their own queued mutations.
• Retry / discard: scoped to owner role per feature.
• DEVELOPER dashboard tile: aggregate across schools.
• Per-school SLI dashboard: ADMIN role.
• Admin offline-mode toggle: ADMIN role only.
• <OfflineDevtools> panel: DEVELOPER role only (gated by session check).

i18n

30 new dictionary keys under dictionary.offline.*. Zero hardcoded strings in offline UI code. Arabic strings reviewed by a native speaker before pilot rollout.

Testing strategy

Telemetry & metrics

Every state transition emits a structured event. Event names use the offline.* namespace.

Rollout (feature flag)

Pilot schools (Sudan, King Fahad) opt into full. SaaS marketing remains on default. ADMIN UI in school settings toggles between modes. DEVELOPER role can override any school's mode for testing.

Developer onboarding

A new contributor adds offline support to their feature in five steps.

1. Register a new action handler in src/lib/offline/registry.ts with a typed payload Zod schema and conflict-policy choice.
2. Call useOfflineMutation("yourFeature.actionName", payload) from the client; for reads use useLiveQuery(() => db.yourFeature.where(...).toArray()).
3. Add a Storybook entry for the conflict UI if conflicts are possible.
4. Add a Playwright test in playwright/tests/offline.spec.ts.
5. Add dictionary keys for any new offline strings under dictionary.offline.<feature>.*.

A complete worked example lives at src/components/school-dashboard/attendance/ after EPIC-3 ships.

Foundation gate

EPIC-0 must pass all of the following before any per-role epic starts. Foundation work is not a partial deliverable.

• Dexie tenant DB factory + schema versioning + migration tests merged
• OPFS abstraction with IDB fallback merged + Safari iOS 16.4 manual test passed
• sync-worker.ts runs all mutation replay; main-thread long-task observer reports zero blocks > 16 ms during sync
• actionRegistry + XState mutation lifecycle merged with ≥ 95% unit test coverage
• LZ4 + MessagePack compression measured at ≥ 3× ratio on typical payloads
• SHA-256 content hashing verifies on every replay; tamper test fails closed
• WebSocket cache-invalidate end-to-end latency ≤ 200 ms in staging
• Service worker drains queue on Background Sync event (Chrome) and on tab reopen (iOS)
• <ConflictResolver> atom shipped with Storybook coverage of every conflict policy
• OfflineSyncLog writes from every transition; Sentry breadcrumbs visible in dashboard
• <OfflineDevtools> panel renders for DEVELOPER role and shows live queue state
• Foundation chunk size ≤ 35 KB gzipped (size-limit CI gate)
• Tenant-leak Playwright test green (queue on school-a → switch to school-b → queue invisible)

Foundation work continues until all boxes are checked. No per-role epic starts before then.

Risks and trade-offs

1. IndexedDB + OPFS quotas. Safari iOS caps around 50 MB; Chrome Android allows up to 60% of disk. Mitigation: OPFS for blobs; payloads-only in IDB; navigator.storage.estimate() watchdog warns at 80%; evict cached reads before queued writes.
2. Cross-tenant leak on subdomain switch. Mitigation: DB name namespaced by schoolId; SW reads schoolId from session cookie per-request; explicit Playwright test in Foundation Gate.
3. Stale exam questions vs. integrity. Mitigation: exam-take pre-cache stores paperVersion; server rejects submit on mismatch with structured <PaperVersionConflict>.
4. WhatsApp bridge duplicates. Mitigation: clientMessageId passed through to bridge as idempotency key.
5. Multi-subdomain SW scope. Each school-X.databayt.org gets its own SW scope (correct).
6. iOS Safari Background Sync absence. Mitigation: online event + visibility-change listener in tab; on PWA reopen, sync worker drains queue immediately.
7. OPFS unavailable on older Safari / in-app browsers. Mitigation: storage layer detects capability at init; falls back to IDB blob fields with storage warning.
8. Cold-cache offline page. Mitigation: aggressive shell pre-cache on install; offline page useful even on first visit (shows install CTA).
9. Background Sync throttling. Mitigation: foreground flush is primary path; background sync is best-effort.
10. Time-skew on stored mutations. Mitigation: server records serverAcceptedAt as authoritative; client markedAt retained as audit metadata only.
11. WebSocket connection limits per origin. Mitigation: single socket per tab; SharedWorker-style coordination across tabs of same origin.
12. OS-level storage eviction. Mitigation: PWA install promotes to "managed storage" with eviction guarantees; non-installed users see warning toast.

Detailed timeline (14 weeks, week-by-week)

Two developers, aligned phases. Week numbers are calendar weeks starting at project kickoff.

Buffer: 1 week reserved for staging soak before pilot enablement.

P0 — EPIC-0, 1, 3, 4 (foundation + teacher daily + student high-stakes). P1 — EPIC-2, 5, 6, 9 (read cache, driver, applicant, docs). P2 — EPIC-7, 8 (messaging queue + analytics).

Pilot rollout playbook

Enabling School.offlineMode='full' for a pilot school is a deliberate, observable change. Five steps.

1. Pre-flight (T-7 days). Confirm school on latest release; smoke-test online flows; baseline current connection-failure rate from Sentry; brief admin on changes ("install prompts; pending sync drawer for offline marks").
2. Soft enable (T-0). ADMIN toggles offlineMode='full' in school settings. Service worker registers on next visit. Read cache populates in background; no user-visible change yet beyond install banner.
3. Day 1 monitoring. Watch OfflineSyncLog for first ~50 enqueued mutations; verify all flush successfully; check Sentry for unexpected errors; verify storage quota stays under 80% on sampled devices.
4. Day 7 review. Compare sync success rate, install rate, average time-to-sync against headline metrics. If any below 95% target, root-cause and either patch or roll back to limited.
5. Day 30 retro. Decide: keep on full, promote to default for similar schools, or refine. Document learnings.

Rollback is instant: ADMIN sets offlineMode='limited'. Queue is preserved client-side and drains on next visit when re-enabled.

Smoke test checklist

Manual checks before declaring a feature "offline-done". Run on Safari iOS 16.4, Chrome Android 110, Chrome Desktop 110 each.

• Service worker registered (chrome://serviceworker-internals shows active)
• Manifest installable (install icon visible or "Add to Home Screen" on iOS)
• App-shell loads with Network: Offline after one prior online visit
• Dashboard offline: a page opened while online renders from its saved copy under the offline strip; a page never opened shows "This page isn't on this device yet" and Back returns. Test with airplane mode or the server stopped — the developer tools' Offline setting does not reach the worker's own requests
• Slow network, responses held longer than 4 s: a saved page shows its copy under the slow-connection strip, and Retry refreshes it
• Shared device: sign out, sign in as another account — no page saved by the first account appears, on a slow network too
• Offline page renders with last-sync time + pending-mutation count + storage UI
• Teacher bulk attendance: mark 20 students offline → reload → all visible as pending → reconnect → all flushed → no duplicates
• Student exam: enter answers offline → submit offline → "submission queued" full-screen → reconnect → submitted
• Driver boarding: scan 5 students in tunnel-simulated offline → reconnect → all 5 recorded
• Applicant: upload 5 MB attachment, kill connection mid-upload → reconnect → upload resumes from completed parts in OPFS
• Messaging: send 3 messages offline → bubble shows queued → reconnect → all show sent
• Subdomain switch: queue items on school-a → navigate to school-b → queue invisible → return to school-a → queue intact
• PWA install prompt: visit dashboard 3 times → banner appears → accept → launches as standalone
• SW update: deploy new SW → toast appears → reload completes
• All UI in Arabic when ?lang=ar → strings render right-to-left
• Pending drawer: retry button works; discard button works; both confirm before destructive
• Storage near-full: fill IDB+OPFS to 80% → warning toast appears
• offlineMode='disabled' → no SW registered (verify in DevTools Application tab)
• WebSocket invalidation: write from device A → device B's live query refreshes within 1 s
• Conflict UI: simulate version conflict → <ConflictResolver> shows both sides → user chooses keep/discard
• Main-thread profiler shows no long tasks > 16 ms during sync flush of 50 items

Acceptance criteria — "Production-grade offline shipped"

1. With School.offlineMode='full', a teacher on chrome://devtools network: Offline marks attendance, refreshes, closes the tab, reopens — all marks pending; reconnect replays with zero duplicates and zero main-thread blocks.
2. A student loses connectivity for 10+ minutes mid-exam, continues answering, hits submit, sees "submission queued"; reconnect completes within 30 seconds with zero data loss.
3. SW sync-forms event fires on reconnect; drains the Dexie queue without the page being open.
4. Browser close/reopen preserves the queue (Dexie, not in-memory).
5. Subdomain switch school-a → school-b does NOT replay school-a's queue against school-b.
6. Playwright tests/offline.spec.ts green across all four role flows + tenant safety + conflict resolution.
7. All offline UI strings render in en and ar from dictionary keys; zero hardcoded English in grep.
8. offlineMode='disabled' disables SW registration entirely.
9. Foundation chunk ≤ 35 KB gzipped (CI gate). Per-epic chunks ≤ 15 KB each.
10. Sentry telemetry shows ≥ 99.9% sync success rate over rolling 7-day window across all full-mode schools.
11. Main-thread long-task observer shows zero blocks > 16 ms during sync flush in p99 measurements.
12. WebSocket cache invalidation latency p95 ≤ 200 ms in production.
13. OPFS attachment resume works after killing the upload mid-flight on iOS 16.4.

Key files

Glossary

• Action handler — A server action registered in actionRegistry by string name (e.g. "exam.submit"). Same function called online or via offline replay.
• App shell — The minimal HTML, CSS, and JS needed to render the offline-aware navigation chrome. Pre-cached at install time.
• Background Sync — Browser API that fires a sync event when the device is online, even if no tab is open. Limited browser support.
• Comlink — Library for ergonomic Web Worker RPC.
• Conflict resolution — Policy applied when a queued mutation can no longer be cleanly applied. Default is server-authoritative with structured merge UI.
• Content hash — SHA-256 of the mutation payload, stored on the envelope. Verified on intake and replay. Tamper-evident.
• Dexie — Wrapper library over IndexedDB with rich query semantics, transactions, live queries, schema versioning.
• Idempotency key — Client-generated cuid v2 attached to every mutation. Server uses OfflineSyncLog to dedupe.
• IDB — IndexedDB, the browser-native indexed key-value store. Per-origin quota; persists across reloads.
• LZ4 — Fast compression algorithm; used here via WASM for payload compression > 1 KB.
• MessagePack — Binary serialization format. More compact than JSON for the envelope encoding.
• Mutation envelope — The typed wrapper around a queued write. Carries metadata for replay including idempotency key and content hash.
• Network Information API — navigator.connection.effectiveType / saveData / rtt. Used to adapt UX to connection quality.
• OPFS — Origin Private File System. Browser-native file system scoped to the origin; better than IDB for large blobs.
• PWA — Progressive Web App. An installable, service-worker-backed web app with offline capability.
• Pre-cache — Storing assets or data before the user needs them offline.
• Sync intake — POST /api/offline/sync/{domain}, the per-domain endpoints that receive queued mutations and dispatch them to handlers.
• Sync worker — sync-worker.ts, the Web Worker that handles all offline replay off the main thread.
• Tenant-namespaced — Storage keyed by schoolId so data never leaks across schools.
• XState — Library for finite-state-machine modeling. Used for the mutation lifecycle.

See also

• Multi-tenancy — schoolId scoping rules every offline write must respect
• Database — Prisma + Neon safety protocol for new tables
• Notifications — read-side cache patterns share infrastructure
• Translation — dictionary key conventions for offline strings
• Document Intelligence — prior-art epic-doc template this doc follows
• Architecture — mirror pattern and tenant context resolution
• MVP — maturity badge conventions for tracking epic progress
• Roadmap — quarter-outlook for offline rollout