Exploring the Concept
The initial discussions about Synccraft’s architecture revealed several key design decisions that needed careful consideration. The conversation evolved from a simple “sync library” concept into a comprehensive local-first data synchronization platform.
Sync Backends: A Pluggable Architecture
The first major decision was defining which sync backends to support:
- Google Drive — Using the shared folder as blob storage. The cloud provider handles permissions and change
detection via
changes.list()API. - OneDrive — Same approach, using
delta()API for change detection. - Custom API — A RESTful backend with SSE (Server-Sent Events) for lightweight notifications. Namespace-scoped with RBAC for fine-grained access control.
- WebRTC — Direct peer-to-peer sync for the ultimate decentralized experience (future goal).
The Key Insight: App-Agnostic Sync
A crucial realization: the sync mechanism should be completely app-agnostic. The library doesn’t know about “home inventory” or “expense ledger”—it only knows about documents and collections. Relations between documents (like a task belonging to a project) are handled by the application layer.
This means:
- Deleting a project doesn’t cascade-delete tasks at the sync level
- If inconsistencies are detected, the app decides how to resolve them
- The sync engine is a dumb pipe—it moves documents, nothing more
Document-Level Sync with Metadata
The data model evolved to support document-level sync with rich metadata:
- Flat JSON documents with encrypted content
- ULID-based file paths for time-ordered, scalable storage
- Metadata for versioning, conflict detection, and tombstone handling
The app-agnostic approach to sync is philosophically clean. By refusing to handle relational concerns at the sync level, Synccraft avoids the complexity that plagues most distributed databases. This separation of concerns means the sync engine remains simple and predictable, while applications retain full control over their data relationships.