docs/sync-and-op-log/README.md
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).
| 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 file-based sync | diagrams/04-file-based-sync.md |
| Understand SuperSync encryption | supersync-encryption-architecture.md |
| 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 |
| 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 |
| 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) |
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)
| 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 |
| 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 |
The Operation Log treats the database as a timeline of events rather than mutable state:
Vector clocks track causality for conflict detection:
EQUAL, LESS_THAN, GREATER_THAN, or CONCURRENTCONCURRENT indicates a true conflict requiring resolutionEffects 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.
src/app/op-log/sync-providers/
├── super-sync/ # SuperSync server provider
├── file-based/ # File-based providers
│ ├── file-based-sync-adapter.service.ts # Unified adapter for file providers
│ ├── file-based-sync.types.ts # FileBasedSyncData types
│ ├── webdav/ # WebDAV provider
│ ├── dropbox/ # Dropbox provider
│ └── local-file/ # Local file sync provider
├── provider-manager.service.ts # Provider activation/management
├── wrapped-provider.service.ts # Provider wrapper with encryption
└── credential-store.service.ts # OAuth/credential storage
src/app/op-log/
├── core/ # Core types and operations
├── persistence/ # IndexedDB storage
├── sync/ # Sync orchestration
└── validation/ # Data validation and repair
| Location | Content |
|---|---|
| vector-clocks.md | Vector clock implementation details |
| packages/super-sync-server/ | SuperSync server implementation |
| background-info/ | Research and best practices documents |
| 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.