How drewmccormack/forked works
This project is a Swift package that offers a framework for managing and merging shared data in an “offline‐first” or “local‐first” style. It is composed of several modular components that work together to offer safe, atomic data modifications and sophisticated, Git-inspired merging (“forking”) behavior. In essence, the system is designed around a core data module that uses branching and merging (by tracking a common ancestor) to avoid race conditions and enable conflict resolution via customizable “Mergeable” types.
Main Components
• Core Library (Forked):
– Represents the heart of the framework.
– Provides the ForkedResource type and core mechanisms for creating forks, tracking changes, and managing shared data without locks.
• Merging Module (ForkedMerge):
– Contains standard merging algorithms, including implementations of Conflict-Free Replicated Data Types (CRDTs).
– Provides the functions and types that implement 3‑way merging algorithms.
• Model Definition Module (ForkedModel):
– Uses Swift macros (like @ForkedModel and @Merged) to auto‑generate mergeable models.
– Abstracts merging behavior for complex data types by letting each property be merged independently.
• Cloud Synchronization Module (ForkedCloudKit):
– Integrates with iCloud (via CloudKit) for multi‑device synchronization.
– Uses a CloudKitExchange component to sync ForkedResources between devices.
• Sample Applications:
– Several sample apps (e.g., “A Race of Actors”, “Forked Model”, “Forking Simple iCloud”, “Forkers”) illustrate how different uses of the framework work with real-world UIs, data models, and synchronization.
Relationships and Interactions
– The Core Library (Forked) underpins the system and is a dependency for all other submodules.
– The merging algorithms found in ForkedMerge extend the core’s “Mergeable” protocol. When a fork is to be merged, the system performs a 3‑way merge using the common ancestor, the current fork value, and the conflicting “subordinate” fork.
– ForkedModel sits on top of the core and the merge module by providing Swift macros so a developer simply annotates properties with @Merged. It thereby leverages the default or custom merging algorithms.
– ForkedCloudKit interfaces with the core to persist and synchronize data through iCloud. It routes changes from the local forked resources to the cloud, and conversely, updates the local state when changes are received.
– Samples and tests demonstrate how these modules integrate. They act as practical “client applications” that use the core functionality to update, merge, and synchronize data.
Architectural Patterns and Design Principles
– Modular Architecture: Each subpackage has a single responsibility. Use distinct nodes for “Forked”, “ForkedMerge”, “ForkedModel”, and “ForkedCloudKit”.
– Decentralized Data Management: The system uses a Git-inspired branching model to avoid serialization issues that lead to race conditions.
– Extensibility: By encapsulating merging algorithms (and even allowing custom implementations, as seen with AccumulatingInt), you ensure that developers can tailor the behavior if desired.
– Offline-First and Local-First Design: Although it integrates with iCloud, the underlying design emphasizes local concurrency, making it robust in offline or unstable connectivity scenarios.
Including Relevant Technologies and Details
– Label nodes clearly: For each module, include a label (e.g., “Core: ForkedResource Management”, “Merging: CRDT/3‑way merge algorithms”, “Model Generation: Swift Macros via ForkedModel”, “Cloud Integration: iCloud/CloudKit Sync”).
• From the client (sample apps/UI) to the Core Library (data updates).