Mirrors/super-productivity
1
0
Fork 0
mirror of https://github.com/johannesjo/super-productivity.git synced 2026-07-17 16:37:43 +00:00
Code Issues Projects Releases Wiki Activity
super-productivity/docs/sync-and-op-log
History
Johannes Millan 291995f343 Merge remote-tracking branch 'origin/master' into feat/sync-55222e 
* origin/master: (25 commits)
  refactor(tasks): extract shared task ordering helpers (#8926)
  feat(sync): conflict journal + disjoint-field auto-merge + review UI (#8874)
  refactor(config): reduce duplicated form and selector boilerplate (#8928)
  feat(work-view): show break time today (#8909)
  feat(tasks): navigate from empty add-subtask input (#8916)
  docs(development): add instructions for setting up local tests with Chromium (#8887)
  chore(lint): remove unused eslint-disable directives (#8913)
  fix(accessibility): add ARIA roles, live regions, and alt attributes to banner component (#8888)
  chore(ui): removes dead utilities and op-log leftovers [#8260 - Tier A] (#8892)
  fix(app): hide donation page on macOS (#8915)
  chore(scripts): remove one-off codemod scripts [#8260 - Tier A] (#8893)
  fix(sync): harden SuperSync E2EE against metadata tampering (GHSA-8pxh-mgc7-gp3g) (#8904)
  feat: add Home Assistant Bridge to community plugins (#8891)
  docs(sync): note local-file rev-check/write is non-atomic (#8898) (#8902)
  18.14.0
  fix(tasks): remove postal-mime dep and harden eml import (#8901)
  style(tasks): elevate add-subtask input
  fix(config): restore day-start offset after operation replay (#8899)
  fix(task-repeat): allow selecting day-of-month recurrence (#8896)
  feat(plugins): add Todoist import plugin with Import/Export launcher (#8882)
  ...

# Conflicts:
#	docs/wiki/3.06-User-Data.md
#	src/app/op-log/backup/backup.service.spec.ts
#	src/app/op-log/backup/backup.service.ts
#	src/app/op-log/sync/conflict-resolution.service.ts
2026-07-11 18:50:32 +02:00
..
diagrams docs(sync): document atomic checkpoint, db v8 barrier and rebuild undo 2026-07-11 18:06:20 +02:00
conflict-journal-and-review.md feat(sync): conflict journal + disjoint-field auto-merge + review UI (#8874) 2026-07-11 17:48:46 +02:00
contributor-sync-model.md docs(sync): consolidate sync docs + enforce the contributor model 2026-05-15 16:51:50 +02:00
file-based-sync-flowchart.md refactor(sync): remove unused error classes, dialog, and constructor-time logging (phase 1, #8325) (#8510) 2026-06-20 13:36:56 +02:00
operation-log-architecture.md Merge remote-tracking branch 'origin/master' into feat/sync-55222e 2026-07-11 18:50:32 +02:00
operation-rules.md docs(sync): document atomic checkpoint, db v8 barrier and rebuild undo 2026-07-11 18:06:20 +02:00
package-boundaries.md refactor(sync-core): drop shared-schema vector-clock compat re-export anda app enum (#8441) 2026-06-17 16:21:26 +02:00
README.md feat(sync): conflict journal + disjoint-field auto-merge + review UI (#8874) 2026-07-11 17:48:46 +02:00
sqlite-migration-followup.md chore(ui): removes dead utilities and op-log leftovers [#8260 - Tier A] (#8892) 2026-07-11 13:05:34 +02:00
sqlite-migration.md feat(op-log): validate SQLite backend + IDB→SQLite migration + backend-aware init (#7931) (#7954) 2026-06-02 17:26:23 +02:00
supersync-encryption-architecture.md chore(scripts): remove one-off codemod scripts [#8260 - Tier A] (#8893) 2026-07-11 10:36:24 +02:00
supersync-scenarios-flowchart.md fix(sync): handle initial provider setup safely 2026-07-11 11:25:57 +02:00
supersync-scenarios.md docs(sync): document atomic checkpoint, db v8 barrier and rebuild undo 2026-07-11 18:06:20 +02:00
vector-clocks.md refactor(sync-core): drop shared-schema vector-clock compat re-export anda app enum (#8441) 2026-06-17 16:21:26 +02:00

README.md

Operation Log & Sync Documentation

The Operation Log is the single sync system for all providers (SuperSync, WebDAV, Dropbox, LocalFile). It is an event-sourced persistence + sync layer: the log is the source of truth, current state is derived by replaying it, and vector clocks detect concurrent edits.

                         User Action
                              │
                              ▼
                         NgRx Store  (runtime source of truth)
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   │                   ▼
    OpLogEffects              │             Other Effects
          │                   │
          ├──► SUP_OPS ◄───────┘   (local persistence — IndexedDB)
          │
          └──► Sync Providers
               ├── SuperSync   (operation-based, real-time)
               └── WebDAV / Dropbox / LocalFile  (file-based, single sync-data.json)

Start here

You want to… Read
Write an effect/reducer/bulk-dispatch correctly contributor-sync-model.md — the one invariant, enforced by lint
Understand the whole architecture + why it's built this way operation-log-architecture.md — Parts A–F + rejected alternatives
See it visually diagrams/ — 8 topic diagrams

Reference docs

Document Scope
operation-log-architecture.md Authoritative architecture: Local Persistence (A), File-Based Sync (B), Server Sync (C), Validation & Repair (D), Smart Archive (E), Atomic State Consistency (F), and Why this architecture: rejected alternatives
contributor-sync-model.md The single sync invariant for contributors (one intent = one op; replayed/remote ops must not re-trigger effects)
operation-rules.md Design rules and guidelines for operations
package-boundaries.md Dependency/ownership boundaries for @sp/sync-core, @sp/sync-providers, app wiring
conflict-journal-and-review.md Conflict journal (device-local record of LWW auto-resolutions), disjoint-field auto-merge, /sync-conflicts review UI
vector-clocks.md Vector clock implementation, pruning, history
supersync-encryption-architecture.md End-to-end encryption (AES-256-GCM + Argon2id)
diagrams/ Mermaid diagrams split by topic

Scenario catalogs (expected behavior)

Document Scope
supersync-scenarios.md Concrete SuperSync scenarios A–G with expected behavior
supersync-scenarios-flowchart.md Visual decision tree for the SuperSync scenarios
file-based-sync-flowchart.md Visual decision tree for file-based providers

Related

Location Content
packages/super-sync-server/ SuperSync server implementation
ARCHITECTURE-DECISIONS.md Load-bearing product/data decisions

Historical design notes and superseded plans are not kept as docs; they live in git history (reference the relevant commit if you need the rationale).