$ show floccusaddon/floccus
Floccus is a cross-platform bookmark synchronization application that runs as a browser extension (Chrome, Firefox, Edge) and a native mobile app (Android, iOS via Capacitor). Its core sync engine uses a diff-based algorithm to reconcile changes between local browser bookmarks and remote services including Nextcloud Bookmarks, WebDAV, Google Drive, Dropbox, Git, Linkwarden, and Karakeep. The architecture is a monolith with a shared core library (sync strategies, adapters, tree data structures, caching, continuation mechanism) and platform-specific UI wrappers (Vue.js options page for the extension, Vue + Vuetify for the mobile app). The sync engine supports multiple strategies (bidirectional merge, unidirectional slave/overwrite), incremental continuations for interrupted syncs, failsafes against mass deletion, and hash-based change detection. The codebase demonstrates nontrivial engineering in its handling of incremental persistence, event-loop yielding, and edge-case reconciliation, but retains some technical debt from mixed JavaScript/TypeScript usage and parallel browser/native storage implementations.
The LLM identified 5 files worth highlighting for reuse:
A decorator that wraps any local tree implementation (BrowserTree, NativeTree) with a cache tree layer. It conditionally exposes a `bulkImportFolder` capability only when the wrapped tree supports it, and delegates all other operations transparently. This is a clean, isolated pattern for adding caching behavior without modifying the wrapped tree, and could be extracted into a generic tree-caching library with minimal changes.
A generic diff data structure that computes and manages CREATE, UPDATE, MOVE, REMOVE, and REORDER actions between two bookmark trees. It supports incremental persistence – each action can be serialized as a row for continuation storage, enabling interrupted syncs to resume without reprocessing. It also provides retraction, commitment, topological sorting of moves to avoid dependency cycles, and compaction. The core diff logic could be extracted for other tree-synchronization domains.
Implements a resilient scheduling mechanism for sync operations with exponential backoff, retry limits, and detection of network-recovery events (using `navigator.onLine` and online/offline events). The schedule adapts based on previous failures and supports immediate retry on connectivity restoration. This pattern is reusable for any periodic task that needs graceful degradation under intermittent failures.
A registry-and-factory pattern that maps account types (string identifiers like 'nextcloud-bookmarks', 'webdav', 'google-drive') to adapter constructor functions. Supports dynamic registration of new adapters via `register()`, making the sync backend set extensible without modifying the core sync engine. This is a clean, isolated pattern for plugin-style architecture in any multi-backend application.
Defines the core `Folder` and `Bookmark` data model classes used throughout the sync engine. Each node maintains a child index, computes hierarchical hashes (SHA-256, xxhash3, murmur3) for efficient change detection, and supports tag normalization and fingerprinting. The `createIndex()`, `updateIndex()`, and `removeFromIndex()` methods provide incremental index maintenance. This is a well-crafted tree structure that could be reused in any application requiring hash-versioned hierarchical data.