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/README.md
Johannes Millan 42e6626b76 docs(sync): consolidate sync docs + enforce the contributor model 
Collapse the sprawling, partly-stale docs/sync-and-op-log/ tree into a
small authoritative set and make the sync-correctness invariant
partly lint-enforced instead of convention-only.

Docs:
- Delete superseded/duplicate/provably-stale design, plan, and
  background-research docs (quick-reference, the architecture-diagrams
  monolith, the "Hybrid Manifest" docs describing code that does not
  exist, completed long-term plans, LLM-synthesis analyses).
- Salvage load-bearing decision history into the surviving docs before
  deletion: rejected-alternatives rationale -> operation-log-architecture
  ("Why this architecture"); vector-clock pruning incident history ->
  vector-clocks.md; archive-payload optimization -> architecture E.7.
- Add contributor-sync-model.md as the single-invariant entry point
  (one user intent = one op; replayed/remote ops must not re-trigger
  effects), with a decision table mapping to the enforcing linters.
- Repoint external/internal cross-refs; add CONTRIBUTING.md + CLAUDE.md
  pointers; record the migration in a dated docs/plans/ design doc.

Enforcement (new eslint-local-rules):
- no-actions-in-effects (error): effects must inject LOCAL_ACTIONS /
  ALL_ACTIONS, never the raw @ngrx/effects Actions stream.
- no-multi-entity-effect (warn, heuristic): flags a literal returned
  array of >=2 action-creator calls; docstring + valid-case specs pin
  exactly which shapes are and are not detected.
- run-specs.js runner wired into `npm run lint` via test:lint-rules;
  refuses to run under test-framework globals and counts RuleTester.run
  invocations so a spec that asserts nothing fails instead of passing.
- Correct the ALL_ACTIONS JSDoc in local-actions.token.ts to match
  reality (archive-operation-handler uses LOCAL_ACTIONS).

Reviewed via parallel multi-agent review; findings W1/W2/W4 and a
dangling doc anchor addressed.
2026-05-15 16:51:50 +02:00

5.9 KiB
Raw Blame History

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
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).