Mirrors/super-productivity
1
0
Fork 0
mirror of https://github.com/johannesjo/super-productivity.git synced 2026-01-23 02:36:05 +00:00
Code Issues Projects Releases Wiki Activity

docs(sync): update operation-log docs to reflect current implementation

Browse source 
- Update README.md with correct links and implementation status
- Add E2EE to implementation status (now complete)
- Update e2e-encryption-plan.md to mark as implemented
- Update operation-log-architecture.md:
  - Add missing service files to file reference section
  - Add E2EE to Part C and "Recently Completed" sections
  - Fix broken references, update last modified date
- Remove reference to non-existent tiered-archive-proposal.md
This commit is contained in:
Johannes Millan 2025-12-27 11:44:30 +01:00
parent 9c55690ebd
commit c1575d7669
3 changed files with 49 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

46
docs/sync-and-op-log/README.md
View file

@ -6,13 +6,14 @@ This directory contains the architectural documentation for Super Productivity's
## Quick Start
| If you want to... | Read this |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| Understand the overall architecture | [operation-log-architecture.md](./operation-log-architecture.md) |
| See visual diagrams | [operation-log-architecture-diagrams.md](./operation-log-architecture-diagrams.md) |
| Learn the design rules | [operation-rules.md](./operation-rules.md) |
| Understand file-based sync | [hybrid-manifest-architecture.md](./hybrid-manifest-architecture.md) |
| Understand legacy PFAPI sync | [pfapi-sync-persistence-architecture.md](./pfapi-sync-persistence-architecture.md) |
| If you want to... | Read this |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| Understand the overall architecture | [operation-log-architecture.md](./operation-log-architecture.md) |
| See visual diagrams | [operation-log-architecture-diagrams.md](./operation-log-architecture-diagrams.md) |
| Learn the design rules | [operation-rules.md](./operation-rules.md) |
| Understand file-based sync | [hybrid-manifest-architecture.md](./long-term-plans/hybrid-manifest-architecture.md) |
| Understand SuperSync encryption | [supersync-encryption-architecture.md](./supersync-encryption-architecture.md) |
| Understand legacy PFAPI sync | [pfapi-sync-persistence-architecture.md](./pfapi-sync-persistence-architecture.md) |
## Documentation Overview
@ -26,18 +27,19 @@ This directory contains the architectural documentation for Super Productivity's
### Sync Architecture
| Document | Description | Status |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------- |
| [hybrid-manifest-architecture.md](./hybrid-manifest-architecture.md) | File-based sync optimization using embedded operations buffer and snapshots (WebDAV/Dropbox) | ✅ Implemented |
| [pfapi-sync-persistence-architecture.md](./pfapi-sync-persistence-architecture.md) | Legacy PFAPI sync system that coexists with operation log | ✅ Active |
| Document | Description | Status |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | -------------- |
| [hybrid-manifest-architecture.md](./long-term-plans/hybrid-manifest-architecture.md) | File-based sync optimization using embedded operations buffer and snapshots (WebDAV/Dropbox) | ✅ Implemented |
| [supersync-encryption-architecture.md](./supersync-encryption-architecture.md) | End-to-end encryption for SuperSync (AES-256-GCM + Argon2id) | ✅ Implemented |
| [pfapi-sync-persistence-architecture.md](./pfapi-sync-persistence-architecture.md) | Legacy PFAPI sync system that coexists with operation log | ✅ Active |
### Planning & Proposals
| Document | Description | Status |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------- |
| [e2e-encryption-plan.md](./e2e-encryption-plan.md) | End-to-end encryption design proposal | 📋 Planned |
| [tiered-archive-proposal.md](./tiered-archive-proposal.md) | Multi-tier archive storage proposal | 📋 Planned |
| [operation-payload-optimization-discussion.md](./operation-payload-optimization-discussion.md) | Discussion on payload optimization strategies | 📋 Historical |
| Document | Description | Status |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------- |
| [replace-pfapi-with-oplog-plan.md](./long-term-plans/replace-pfapi-with-oplog-plan.md) | Plan to unify sync by replacing PFAPI with operation log | 📋 Planned |
| [e2e-encryption-plan.md](./long-term-plans/e2e-encryption-plan.md) | Original E2EE design (see supersync-encryption for impl) | ✅ Implemented (Dec 2025) |
| [operation-payload-optimization-discussion.md](./operation-payload-optimization-discussion.md) | Discussion on payload optimization strategies | 📋 Historical |
## Architecture at a Glance
@ -111,12 +113,11 @@ This prevents duplicate side effects when syncing operations from other clients.
## Related Documentation
| Location | Content |
| ---------------------------------------------------------------------- | ----------------------------------- |
| [/docs/sync/vector-clocks.md](/docs/sync-and-op-log/vector-clocks.md) | Vector clock implementation details |
| [/docs/ai/sync/](/android/sync/) | Historical planning documents |
| [/packages/super-sync-server/](/packages/super-sync-server/) | SuperSync server implementation |
| [/src/app/pfapi/api/sync/README.md](/src/app/pfapi/api/sync/README.md) | PFAPI sync overview |
| Location | Content |
| ---------------------------------------------------------------- | ------------------------------------- |
| [vector-clocks.md](./vector-clocks.md) | Vector clock implementation details |
| [packages/super-sync-server/](../../packages/super-sync-server/) | SuperSync server implementation |
| [background-info/](./background-info/) | Research and best practices documents |
## Implementation Status
@ -126,6 +127,7 @@ This prevents duplicate side effects when syncing operations from other clients.
| Legacy Sync Bridge (Part B) | ✅ Complete |
| Server Sync (Part C) | ✅ Complete (single-version) |
| Validation & Repair (Part D) | ✅ Complete |
| End-to-End Encryption | ✅ Complete (AES-256-GCM + Argon2id) |
| Cross-version Sync (A.7.11) | ⚠️ Not implemented |
| Schema Migrations | ✅ Infrastructure ready (no migrations defined yet) |

7
docs/sync-and-op-log/long-term-plans/e2e-encryption-plan.md
View file

@ -1,5 +1,12 @@
# E2E Encryption for SuperSync Server
> **Status:** ✅ **Implemented** (December 2025)
>
> This plan has been fully implemented. For the current implementation details, see:
>
> - [supersync-encryption-architecture.md](../supersync-encryption-architecture.md) - Implementation documentation with diagrams
> - `src/app/core/persistence/operation-log/sync/operation-encryption.service.ts` - Core encryption service
## Summary
Add end-to-end encryption to SuperSync where the server cannot read operation payloads. Users provide a separate encryption password which is used to derive an encryption key client-side. This is the same approach used by legacy sync providers (Dropbox, WebDAV, Local File).

23
docs/sync-and-op-log/operation-log-architecture.md
View file

@ -2,7 +2,7 @@
**Status:** Parts A, B, C, D Complete (single-version; cross-version sync requires A.7.11)
**Branch:** `feat/operation-logs`
**Last Updated:** December 12, 2025
**Last Updated:** December 27, 2025
---
@ -1904,6 +1904,11 @@ When adding new entities or relationships:
- Bounded memory during download (`MAX_DOWNLOAD_OPS_IN_MEMORY = 50,000`)
- Integration test suite (`sync-scenarios.integration.spec.ts`)
- E2E test infrastructure (`supersync.spec.ts` with Playwright)
- **End-to-end encryption** (December 2025):
- `OperationEncryptionService` for payload encryption/decryption
- AES-256-GCM with Argon2id key derivation
- Optional per-provider encryption password
- See [supersync-encryption-architecture.md](./supersync-encryption-architecture.md)
- **Server-side security hardening** (December 2025):
- Structured audit logging for security events
- Structured error codes (`SYNC_ERROR_CODES`) for upload results
@ -1945,6 +1950,7 @@ When adding new entities or relationships:
> **Recently Completed (December 2025):**
>
> - **Server Sync (SuperSync)**: Full upload/download infrastructure with conflict detection, user resolution UI, and integration tests
> - **End-to-End Encryption**: AES-256-GCM payload encryption with Argon2id key derivation via `OperationEncryptionService`
> - **Server Security Hardening**: Audit logging, structured error codes, request deduplication, transaction isolation, input validation, rate limiting
> - **Unified Archive Handling**: `ArchiveOperationHandler` is now the single source of truth for all archive operations, used by both local effects and remote operation application
> - **Simplified OperationCaptureService**: Refactored to FIFO queue with reference equality optimization for detecting changed feature states
@ -1988,16 +1994,21 @@ src/app/core/persistence/operation-log/
│ ├── operation-log-sync.service.ts # Orchestration (Part C)
│ ├── operation-log-download.service.ts # Download ops (API + file fallback)
│ ├── operation-log-upload.service.ts # Upload ops (API + file fallback)
│ ├── operation-encryption.service.ts # E2EE payload encryption (AES-256-GCM)
│ ├── vector-clock.service.ts # Global/entity frontier tracking
│ ├── lock.service.ts # Cross-tab locking (Web Locks + fallback)
│ ├── multi-tab-coordinator.service.ts # BroadcastChannel coordination
│ ├── dependency-resolver.service.ts # Extract/check dependencies
│ ├── conflict-resolution.service.ts # Conflict UI presentation
│ ├── conflict-resolution.service.ts # LWW conflict resolution + user notification
│ ├── sync-import-filter.service.ts # Filter ops invalidated by SYNC_IMPORT
│ ├── immediate-upload.service.ts # Trigger immediate sync on critical ops
│ ├── super-sync-status.service.ts # SuperSync connection status tracking
│ ├── server-migration.service.ts # Server-side schema migration handling
│ ├── operation-write-flush.service.ts # Batch write operations with flush
│ └── operation-sync.util.ts # Sync helper utilities
├── processing/
│ ├── operation-applier.service.ts # Apply ops with fail-fast dependency handling
│ ├── operation-capture.service.ts # FIFO queue for capturing entity changes
│ ├── operation-capture.meta-reducer.ts # Meta-reducer for before/after state capture
│ ├── hydration-state.service.ts # Track hydration/remote ops application state
│ ├── archive-operation-handler.service.ts # Unified handler for archive side effects
│ ├── archive-operation-handler.effects.ts # Routes local actions to ArchiveOperationHandler
│ ├── validate-state.service.ts # Typia + cross-model validation
@ -2034,5 +2045,7 @@ e2e/
# References
- [PFAPI Architecture](./pfapi-sync-persistence-architecture.md) - Legacy sync system
- [Multi-Entity Operations Plan](./multi-entity-operations-plan.md) - Multi-entity operation design
- [Operation Rules](./operation-rules.md) - Payload and validation rules
- [SuperSync Encryption](./supersync-encryption-architecture.md) - End-to-end encryption implementation
- [Hybrid Manifest Architecture](./long-term-plans/hybrid-manifest-architecture.md) - File-based sync optimization
- [Vector Clocks](./vector-clocks.md) - Vector clock implementation details