super-productivity/docs/sync-and-op-log/README.md

Operation Log Documentation

Last Updated: January 2026

This directory contains the architectural documentation for Super Productivity's Operation Log system - an event-sourced persistence and synchronization layer that handles ALL sync providers (SuperSync, WebDAV, Dropbox, LocalFile).

Quick Start

If you want to...	Read this
Understand the overall architecture	operation-log-architecture.md
See visual diagrams	diagrams/ (split by topic)
Learn the design rules	operation-rules.md
Understand package boundaries	package-boundaries.md
Understand file-based sync	diagrams/04-file-based-sync.md
Understand SuperSync encryption	supersync-encryption-architecture.md

Documentation Overview

Core Documentation

Document	Description	Status
operation-log-architecture.md	Comprehensive architecture reference covering Parts A-F: Local Persistence, File-Based Sync, Server Sync, Validation & Repair, Smart Archive Handling, and Atomic State Consistency	Active
diagrams/	Mermaid diagrams split by topic (local persistence, server sync, file-based sync, etc.)	Active
operation-rules.md	Design rules and guidelines for the operation log store and operations	Active
package-boundaries.md	Dependency direction and ownership boundaries for @sp/sync-core, @sp/sync-providers, and app sync wiring	Active

Sync Architecture

Document	Description	Status
diagrams/04-file-based-sync.md	File-based sync with single sync-data.json (WebDAV/Dropbox/LocalFile)	Implemented
diagrams/02-server-sync.md	SuperSync server sync architecture	Implemented
supersync-encryption-architecture.md	End-to-end encryption for SuperSync (AES-256-GCM + Argon2id)	Implemented

Historical / Completed Plans

Document	Description	Status
replace-pfapi-with-oplog-plan.md	Plan to unify sync by replacing PFAPI with operation log	Completed (Jan 2026)
e2e-encryption-plan.md	Original E2EE design (see supersync-encryption for impl)	Implemented (Dec 2025)

Architecture at a Glance

The Operation Log system is the single sync system for all providers:

                         User Action
                              │
                              ▼
                         NgRx Store
                   (Runtime Source of Truth)
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   │                   ▼
    OpLogEffects              │             Other Effects
          │                   │
          ├──► SUP_OPS ◄──────┘
          │    (Local Persistence - IndexedDB)
          │
          └──► Sync Providers
               ├── SuperSync (operation-based, real-time)
               ├── WebDAV (file-based, single-file snapshot)
               ├── Dropbox (file-based, single-file snapshot)
               └── LocalFile (file-based, single-file snapshot)

Sync Provider Types

Provider Type	Providers	How It Works
Server-based	SuperSync	Individual operations uploaded/downloaded via HTTP API
File-based	WebDAV, Dropbox, LocalFile	Single sync-data.json file with state snapshot + recent ops

The Core Parts

Part	Purpose	Description
A. Local Persistence	Fast writes, crash recovery	Operations stored in IndexedDB (SUP_OPS), with snapshots for fast hydration
B. File-Based Sync	WebDAV/Dropbox/LocalFile	Single-file sync with state snapshot and embedded operations buffer
C. Server Sync	Operation-based sync	Upload/download individual operations via SuperSync server
D. Validation & Repair	Data integrity	Checkpoint validation with automatic repair and REPAIR operations

Additional architectural patterns:

Pattern	Purpose
E. Smart Archive Handling	Deterministic archive operations synced via instructions, not data
F. Atomic State Consistency	Meta-reducers ensure multi-entity changes are atomic

Key Concepts

Event Sourcing

The Operation Log treats the database as a timeline of events rather than mutable state:

• Source of Truth: The log is truth; current state is derived by replaying the log
• Immutability: Operations are never modified, only appended
• Snapshots: Periodic snapshots speed up hydration (replay from snapshot + tail ops)

Vector Clocks

Vector clocks track causality for conflict detection:

• Each client has its own counter in the vector clock
• Comparison reveals: EQUAL, LESS_THAN, GREATER_THAN, or CONCURRENT
• CONCURRENT indicates a true conflict requiring resolution

LOCAL_ACTIONS Token

Effects that perform side effects (snacks, external APIs, UI) must use LOCAL_ACTIONS instead of Actions:

private _actions$ = inject(LOCAL_ACTIONS); // Excludes remote operations

This prevents duplicate side effects when syncing operations from other clients.

Key Files

Sync Packages

packages/sync-core/src/
├── operation.types.ts          # Generic operation primitives
├── vector-clock.ts             # Compare/merge/prune algorithms
├── conflict-resolution.ts      # Pure conflict helpers
├── replay-coordinator.ts       # Generic remote replay ordering
└── ports.ts                    # App-side orchestration contracts

packages/sync-providers/src/
├── super-sync/                 # SuperSync provider implementation
├── file-based/dropbox/         # Dropbox provider implementation
├── file-based/webdav/          # WebDAV + Nextcloud providers
├── file-based/local-file/      # LocalFile provider classes
└── provider-types.ts           # Provider-neutral contracts

App Sync Wiring

src/app/op-log/sync-providers/
├── sync-providers.factory.ts       # Composes app deps into package providers
├── credential-store.service.ts     # OAuth/credential storage implementation
├── wrapped-provider.service.ts     # Provider wrapper with encryption
├── file-based/                     # File-based adapter + app shims
└── super-sync/                     # SuperSync app shims + validators

Core Operation Log

src/app/op-log/
├── core/                           # Core types and operations
├── persistence/                    # IndexedDB storage
├── sync/                           # Sync orchestration
└── validation/                     # Data validation and repair

Related Documentation

Location	Content
vector-clocks.md	Vector clock implementation details
packages/super-sync-server/	SuperSync server implementation
background-info/	Research and best practices documents

Implementation Status

Component	Status
Local Persistence (Part A)	Complete
File-Based Sync (Part B)	Complete (WebDAV, Dropbox, LocalFile)
Server Sync (Part C)	Complete (SuperSync)
Validation & Repair (Part D)	Complete
End-to-End Encryption	Complete (AES-256-GCM + Argon2id)
PFAPI Elimination	Complete (Jan 2026)
Cross-version Sync (A.7.11)	Documented (not yet implemented)
Schema Migrations	Infrastructure ready (no migrations defined yet)

See operation-log-architecture.md#implementation-status for detailed status.