Imagine a project tool that works perfectly offline, never relies on a server, and makes your data as portable as a USB stick. That’s the core idea behind Threlmark’s local-first architecture. It’s a radical shift—treating the local disk as the contract, not a cloud or database.

This approach transforms how you think about data, flow, and collaboration. And it’s not just theory. It’s a practical, resilient way to build apps that work everywhere, all the time.

Key Takeaways

• Treat the local filesystem as the primary data source, not a remote server.
• Use atomic file writes and JSON files for safe, portable, and conflict-resilient data.
• Design your app to read, write, and merge files directly to simplify offline support.
• Sync is just copying files—no complicated database locking needed.
• Ideal for small to medium projects that benefit from offline resilience and simplicity.

What Does ‘Disk Is the Contract’ Actually Mean?

At its heart, ‘disk is the contract’ means the app’s behavior and data integrity depend on files stored on your local filesystem. Instead of a server holding the source of truth, your files are the source—every read, write, and sync is driven by these files.

For example, Threlmark uses plain JSON files that represent project boards, cards, and dependencies. When you open your app, it reads those files directly, making the data instantly accessible, even offline.

This approach shifts the entire model from a cloud-first mindset to a local-first architecture. Your data lives on disk, and everything else is just a way to view or sync that data.

Understanding this is crucial because it emphasizes that the core data is stored in a format that is both human-readable and easily manipulated by a wide range of tools. This flexibility allows for better control, transparency, and resilience, but it also requires developers to think differently about data consistency and versioning. The tradeoff is that you need to manage conflict resolution and synchronization explicitly, rather than relying on a database engine to handle these complexities for you.

How Threlmark Uses JSON Files to Keep Data Safe and Portable

Threlmark organizes all data into individual JSON files stored on disk. You can learn more about similar architectures in this article. Each project, card, or link gets its own file under a structured folder hierarchy. For example, each card lives in items/, making it easy to update or replace without touching the rest.

This structure offers four clear benefits, similar to those discussed in this overview:

• Inspectability: You can open files with any editor and see the data directly.
• Portability: Moving or copying files is enough to back up or migrate your data.
• Interoperability: Any tool can join in—just read/write files in the same format.
• Restartability: No in-memory state to lose; the system always reads from disk.

But beyond these benefits, this approach fundamentally changes how data is managed and perceived, as explored in this analysis. Because each piece of data is isolated, developers can easily track changes, revert to previous states, or integrate with external tools without complex database migrations or vendor lock-in. However, this also means that consistency depends heavily on disciplined file management and conflict resolution strategies during sync. The tradeoff is that while this system is simple and robust for small to medium datasets, scaling to large datasets or highly concurrent environments requires careful planning and additional mechanisms to handle conflicts and ensure data integrity.

Designing for Offline Resilience and Data Integrity

Building on the idea of storing data in JSON files, it’s essential to design your app with offline resilience in mind. For more on offline data strategies, see this resource. This means implementing atomic file operations to prevent corruption during writes and ensuring that your app can handle partial or failed syncs gracefully.

For example, using temporary files during save operations ensures that incomplete writes don’t corrupt your data. Additionally, maintaining versioning within your JSON files or using timestamps can help detect conflicts early and facilitate effective merging strategies.

By thinking carefully about these aspects from the start, you can create a system that remains reliable even when offline or facing network interruptions. This requires a disciplined approach to file management and conflict resolution but results in a highly resilient application that can operate seamlessly in diverse environments.

How Threlmark Uses JSON Files to Keep Data Safe and Portable

Threlmark organizes all data into individual JSON files stored on disk. Each project, card, or link gets its own file under a structured folder hierarchy. For example, each card lives in items/, making it easy to update or replace without touching the rest.

This structure offers four clear benefits:

• Inspectability: You can open files with any editor and see the data directly.
• Portability: Moving or copying files is enough to back up or migrate your data.
• Interoperability: Any tool can join in—just read/write files in the same format.
• Restartability: No in-memory state to lose; the system always reads from disk.

But beyond these benefits, this approach fundamentally changes how data is managed and perceived. Because each piece of data is isolated, developers can easily track changes, revert to previous states, or integrate with external tools without complex database migrations or vendor lock-in. However, this also means that consistency depends heavily on disciplined file management and conflict resolution strategies during sync. The tradeoff is that while this system is simple and robust for small to medium datasets, scaling to large datasets or highly concurrent environments requires careful planning and additional mechanisms to handle conflicts and ensure data integrity.

Frequently Asked Questions

How does ‘disk is the contract’ improve offline work?

Because your data lives directly on disk as JSON files, you can access and edit it anytime, anywhere. No need for a server or internet connection—your files are your truth.

How do conflicts get resolved when two devices edit the same data?

Threlmark compares file versions and merges changes based on timestamps or priorities. Conflicts can be auto-resolved or prompted for manual review, just like merging two notes.

Is this approach suitable for large-scale, real-time apps?

It’s best for small to medium projects. Large apps with many users or real-time collaboration might need more complex sync solutions or hybrid models, but for personal or team apps, it’s a perfect fit.

What about schema changes in my JSON files?

Schema migrations require careful planning—updating old files to new formats can be manual or scripted. The key is to version your files and handle migration gracefully, understanding that schema evolution is a tradeoff in this approach.

How secure is storing data as JSON files on my disk?

Security depends on your disk encryption and access controls. Files stored locally are only as safe as your device protection—consider encryption for sensitive data, and be aware that managing security is a tradeoff for simplicity and control.

Conclusion

Adopting a ‘disk is the contract’ mindset flips the traditional app model on its head. Data stored directly on your disk becomes the single source of truth—robust, portable, and ready for offline work.

It’s a straightforward idea with powerful results: simpler code, better resilience, and total control. Imagine a future where your tools keep working, no matter the network. That’s the promise of local-first architecture.