Imagine a world where your project management tool is just a folder full of JSON files on your disk. No server, no cloud, no login required. That’s the core idea behind Threlmark’s local-first architecture, where the disk isn’t just storage — it’s the contract. This approach flips the usual cloud-centric model upside down and offers a fresh way to think about data ownership, offline access, and collaboration.

In this article, you’ll see how Threlmark’s design makes the disk the ultimate authority, how it handles sync and conflicts without a central server, and what tradeoffs this approach involves. If you’re curious about building apps that are fast, private, and resilient — and how to do so without a database in the middle — you’re in the right place.

Key Takeaways

• Treat the local disk as the ultimate source of truth to build resilient, offline-capable apps.
• Use one file per data item to avoid race conditions and simplify conflict management.
• Background sync reconciles device states without a central server, maintaining data consistency.
• Design for security with end-to-end encryption and careful key management in a local-first setup.
• Building with ‘disk is the contract’ shifts complexity from servers to client-side conflict resolution, but offers more control and privacy.

What Does ‘Disk Is the Contract’ Really Mean?

At its core, ‘disk is the contract’ means your app treats the local disk as the single source of truth. The files on your disk, especially in Threlmark’s case, are the definitive record of your data. Nothing is stored in a remote database — instead, your app reads and writes directly to these files, trusting them as the real deal.

Imagine you’re working on a task list in Threlmark. You add, move, or complete a task. Those changes go straight into individual JSON files. When you switch devices or reopen the app, it simply reads the files — no syncing, no conflicts, no cloud needed. That’s the beauty of placing the disk at the center: your data’s state is always saved locally and always authoritative.

This approach aligns with the core local-first principle: the local copy is the primary, trusted version. It’s not just storage; it’s the agreement between your app and your data.

Why does this matter? Because it fundamentally shifts the way developers think about data consistency and control. Instead of relying on remote servers and complex synchronization logic, the developer can focus on ensuring the local data is correct and consistent. This reduces reliance on network conditions, server uptime, and external data sources, leading to more resilient and private applications. For more on this, see private placement markets and investment strategies. However, it also means that managing conflicts and ensuring data integrity across multiple devices becomes a critical design challenge, requiring thoughtful conflict resolution strategies and robust file handling.

How Does Threlmark Sync Data Between Devices?

Threlmark’s sync isn’t a constant stream but a background process that reconciles files across devices. It relies on tracking changes, merging updates, and resolving conflicts—all while keeping the local disk as the master copy. Learn more about local-first architecture at this article. This means that sync is inherently asynchronous and designed to be conflict-aware, which has profound implications for user experience and data integrity.

Why is this important? Because in a local-first setup, conflicts are inevitable—especially when multiple devices are used offline. The system’s ability to intelligently detect, resolve, or flag conflicts determines the app’s reliability and user trust. Threlmark’s approach—using timestamps, CRDTs, or custom conflict rules—aims to preserve the most recent or relevant data, but it also introduces tradeoffs: complexity in conflict resolution, potential for data loss if not handled carefully, and increased developer effort.

Understanding this process helps developers realize that sync isn’t just about copying files; it’s about designing a system that gracefully handles the messy realities of offline work, conflicting edits, and eventual consistency. The key is that the disk remains the ultimate authority, and sync is merely a reconciliation process that respects that authority, rather than overriding it arbitrarily.

What Are the Storage Choices and Why They Matter

Threlmark’s system can use various storage options, depending on the environment. In browsers, it relies on IndexedDB, while on desktop or mobile, it can use the filesystem directly. The key is that each data artifact is a plain JSON file, readable and writable by any tool.

Here’s a quick comparison:

Storage Type	Best Use Case	Advantages	Limitations
IndexedDB	Browser apps, offline web apps	Built-in, asynchronous, easy to integrate with web APIs	Complex API, less portable outside browser
Filesystem	Desktop or mobile apps	Plain files, easy to inspect, portable	Requires native APIs or permissions
Plain JSON Files	Portable, multi-tool workflows	Simple, transparent, no lock-in	Requires careful handling for concurrency

Why does this matter? Because choosing the right storage impacts how easily the app can be built, maintained, and extended. Using plain JSON files, for example, makes the data transparent and accessible, which fosters interoperability and simplifies backup or migration processes. It also means that developers can leverage existing tools like diff, grep, or version control systems to manage data, reducing vendor lock-in and increasing flexibility.

In essence, the storage choices directly influence the app’s resilience, portability, and developer experience—core aspects of the local-first philosophy.

Tradeoffs: The Good, The Bad, and The Challenging

Building with ‘disk as the contract’ offers significant benefits, such as offline resilience and data ownership, but it also introduces complexities that developers must grapple with. The core tradeoff lies in the increased responsibility for conflict management and sync logic. Unlike cloud-based systems where the server handles consistency, here, the developer must design mechanisms to detect, resolve, or prevent conflicts—an often intricate process that can introduce bugs or data loss if not handled carefully.

This approach also demands more from the client device: handling file I/O, managing concurrency, and performing conflict resolution all add layers of complexity. On the upside, this complexity results in a system that is more robust against network failures, offers better privacy, and reduces dependency on external services. But it requires a shift in development mindset: instead of focusing solely on server-side logic, developers need to think in terms of local data integrity, conflict resolution strategies, and background synchronization processes.

Moreover, tradeoffs include potential performance impacts—large files or complex conflict resolution algorithms can slow down the user experience if not optimized. Yet, these tradeoffs are often acceptable, given the increased control and resilience they enable. Ultimately, the decision to adopt disk as the contract hinges on weighing these complexities against the benefits of privacy, offline capability, and user ownership.

What About Security? Is Local-First Safer?

In a local-first setup, your data lives on your device first and foremost. That naturally reduces the attack surface since there’s no constant connection to a server to hack. But security isn’t just about storage — it’s about encryption and access control.

Threlmark can implement end-to-end encryption, so even if someone steals your files, they can’t read your data without the keys. This is a massive privacy win, especially when compared to cloud apps that store data in centralized servers vulnerable to breaches.

However, managing keys and ensuring sync integrity still requires careful handling. The system needs to verify that data changes are genuine and that conflicts are resolved without leaks or corruption. It’s security layered on top of a resilient, file-based infrastructure. This means that while local-first reduces certain attack vectors, it shifts the responsibility to the application to implement robust encryption, key management, and integrity checks—factors that are crucial for truly secure systems.

How Does All This Change the Developer’s Job?

Developers building on a local-first, disk-as-the-contract architecture will find their job simpler in some ways and more complex in others. They no longer need to design complex server-side logic for every feature. Instead, they focus on local data handling, conflict resolution, and sync policies.

For example, an app that tracks personal goals can just store each goal as a JSON file. When the user edits offline, the app updates the file instantly. When online, the sync engine reconciles changes across devices, ensuring everyone sees the latest.

This shift reduces the back-end burden, but it demands a deeper understanding of file-based concurrency, conflict management, and background sync. Developers must now think about how to design conflict resolution rules, how to handle partial failures, and how to ensure data consistency across devices. Tools like [Threlmark](https://github.com/MeyerThorsten/threlmark) help abstract some of these complexities, but the core challenge remains: designing for offline resilience and conflict management is central to the developer’s new role. This paradigm encourages more thoughtful, resilient app design, but requires a shift in skills and mindset.

Frequently Asked Questions

What does ‘disk is the contract’ mean in simple terms?

It means your app treats the files on your disk as the real, authoritative record of your data. Any changes happen directly to those files, and they define the true state of your system.

How does Threlmark keep data in sync across devices?

Threlmark uses background processes that compare, merge, and resolve conflicts between local files on different devices. It relies on change tracking and conflict rules, all while keeping the disk as the ultimate authority.

Is local-first architecture more secure than cloud apps?

Yes, because your data lives primarily on your device, reducing exposure to centralized breaches. When combined with end-to-end encryption, it offers a strong privacy advantage.

What are the biggest challenges of using ‘disk as the contract’?

Managing conflicts, designing robust sync, and handling concurrency can be complex. It requires careful planning, but pays off in offline resilience and data ownership.

Can this approach support real-time collaboration?

Yes, with well-designed sync and conflict resolution, multiple devices can work together seamlessly. But achieving real-time collaboration requires additional mechanisms like CRDTs or commit graphs.

Conclusion

Threlmark’s approach proves that the simplest idea — the disk as the contract — can unlock new levels of resilience, privacy, and portability. It turns your local machine into the defining authority, making your app faster, more private, and more adaptable.

Imagine a world where your data never leaves your device unless you choose it to. That’s the promise of local-first architecture. So, next time you build or choose a tool, ask: does it respect the disk as the contract? If yes, you’re on the path to something truly robust.