mirror of https://github.com/johannesjo/super-productivity.git synced 2026-01-23 02:36:05 +00:00

Johannes Millan 9f0adbb95c docs: fix outdated file paths and types in diagrams

- Fix FileBasedSyncData type: remove non-existent lastSeq, add clientId
- Fix file paths: op-log/processing → op-log/apply
- Fix file paths: features/time-tracking → features/archive
- Fix file path: super-sync not supersync
- Fix vector-clock path: now in op-log/sync/
- Remove non-existent state-capture.meta-reducer.ts reference
- Remove pfapi-migration.service.ts (no longer exists)

docs: remove outdated .bak file references from diagrams

The backup file (sync-data.json.bak) is no longer created during
upload. It's only deleted as cleanup from legacy implementations.

docs: add sync comparison and simple sync flow diagrams

- Add 07-supersync-vs-file-based.md comparing the two sync approaches
- Add 08-sync-flow-explained.md with step-by-step sync explanation
- Remove consolidated unified-oplog-sync-diagrams.md
- Update diagrams README with new entries

docs(sync): reorganize diagrams into subfolder and update for unified architecture

- Create docs/sync-and-op-log/diagrams/ with topic-based diagram files
- Remove outdated PFAPI Legacy Bridge references from diagrams
- Update archive diagrams to use generic "Archive Database" naming
- Fix file paths from sync/providers/ to sync-providers/
- Update quick-reference Area 12 to show unified file-based sync
- Update README to reference new diagram locations

docs: update architecture docs to reflect PFAPI elimination

- Delete obsolete PFAPI documentation:
  - docs/sync-and-op-log/pfapi-sync-persistence-architecture.md
  - docs/sync-and-op-log/pfapi-sync-overview.md
  - docs/plans/pfapi-elimination-status.md

- Update sync-and-op-log/README.md:
  - Describe unified operation log architecture
  - Document file-based sync (Part B) and server sync (Part C)
  - Update file structure to reflect sync-providers location

- Update operation-log-architecture.md:
  - Rewrite Part B from "Legacy Sync Bridge" to "File-Based Sync"
  - Remove all PFAPI code examples and references
  - Update IndexedDB structure diagram (single SUP_OPS database)
  - Update architecture overview to show current provider structure
  - Add notes about PFAPI elimination (January 2026)

- Mark completed implementation plans:
  - replace-pfapi-with-oplog-plan.md - marked as COMPLETED
  - file-based-oplog-sync-implementation-plan.md - marked as COMPLETED

Also includes fix for file-based sync gap detection to handle
snapshot replacement (when "Use Local" is chosen in conflict resolution).

2026-01-08 11:10:29 +01:00

4.1 KiB

Raw Blame History

Operation Log Architecture Diagrams

Last Updated: January 2026

This directory contains visual diagrams explaining the Operation Log sync architecture.

Diagram Index

Diagram	Description	Status
01-local-persistence.md	Local IndexedDB persistence, hydration, compaction	Implemented
02-server-sync.md	SuperSync server API, PostgreSQL, upload/download flows	Implemented
03-conflict-resolution.md	LWW auto-resolution, SYNC_IMPORT filtering, vector clocks	Implemented
04-file-based-sync.md	WebDAV/Dropbox/LocalFile sync via single sync-data.json	Implemented
05-meta-reducers.md	Atomic multi-entity operations, state consistency	Implemented
06-archive-operations.md	Archive side effects, dual-database architecture	Implemented
07-supersync-vs-file-based.md	Comparison of SuperSync and file-based sync providers	Implemented
08-sync-flow-explained.md	Simple explanation of how sync works	Implemented

By Topic

Getting Started:

Start with 01-local-persistence.md to understand how data is stored locally
Then 04-file-based-sync.md or 02-server-sync.md depending on your sync provider

Understanding Conflicts:

03-conflict-resolution.md explains how concurrent edits are resolved

Advanced Topics:

05-meta-reducers.md for atomic multi-entity operations
06-archive-operations.md for archive-specific handling

Comparisons & Overviews:

07-supersync-vs-file-based.md compares the two sync approaches
08-sync-flow-explained.md simple step-by-step sync explanation

By Sync Provider

Provider	Primary Diagram
SuperSync	02-server-sync.md
WebDAV	04-file-based-sync.md
Dropbox	04-file-based-sync.md
LocalFile	04-file-based-sync.md

Document	Description
../operation-log-architecture.md	Comprehensive architecture reference
../operation-rules.md	Design rules and guidelines
../vector-clocks.md	Vector clock implementation details
../quick-reference.md	Quick lookup for common patterns

Diagram Conventions

All diagrams use Mermaid syntax and follow these conventions:

Color	Meaning
Green (`#e8f5e9`)	Success paths, valid states, local operations
Blue (`#e3f2fd`)	Server/API operations, remote operations
Orange (`#fff3e0`)	Storage, file operations, warnings
Red (`#ffebee`)	Errors, conflicts, filtered operations
Purple (`#f3e5f5`)	Results, outputs, final states

4.1 KiB Raw Blame History