Imagine a project management app that never relies on a cloud server. Instead, everything lives right on your disk, in plain JSON files. That’s the core idea behind Threlmark’s local-first architecture — it’s a radically simple yet powerful way to manage data. You’ll see how this approach makes your workflow faster, more reliable, and surprisingly flexible.

In this article, you’ll learn what it really means when we say “disk is the contract,” how this design influences data handling, sync, and conflict resolution, and why it might be the future for your own tools or projects.

Key Takeaways

• Treat disk files as the primary source of truth — it simplifies data management and debugging.
• Use one JSON file per item for collision-free, atomic updates without locks.
• Design self-healing structures like lane ordering to keep the project roadmap consistent.
• Conflict resolution through timestamps and manual merging keeps things straightforward.
• Offline-first design enables seamless work even without network connectivity.

What does ‘disk is the contract’ really mean in Threlmark?

At its core, ‘disk is the contract’ means the files on your hard drive are the authoritative record of your data. No server, no cloud, just a structured set of JSON files. When you open Threlmark, it reads these files directly. When you make changes, they’re written back to disk immediately. Learn more about local-first architecture.

For example, a project card is just a `.json` file in the `items/` folder. If you want to see what’s happening, you can peek at that file — no need to log into a database or API. The entire system hinges on this simple, transparent file structure.

How the JSON-on-disk model keeps data transparent and easy to debug

Threlmark’s data lives in plain JSON files, making it easy to inspect, troubleshoot, and migrate. Say you’re debugging a task stuck in a certain state. Just open the relevant `item.json` file, see the raw data, and understand exactly what’s stored. No opaque database layer hiding the details.

This approach also makes migrating to new formats straightforward. You modify a file, and your tools can handle the transition, thanks to the human-readable structure. It’s like having a digital paper trail of every change.

Why managing files directly makes sync and conflict resolution simpler

In Threlmark, each project item gets its own JSON file, and updates are atomic — they happen one file at a time. This means no complex locking or coordination. When two devices edit the same card, the last write wins. Conflicts are easy to detect by comparing file versions.

For example, editing a task on your laptop and your phone simultaneously might create a conflict, but resolving it simply involves choosing which JSON file to keep or merging changes manually.

Self-healing lane structure keeps your roadmap consistent

The lane order for your project is stored separately in `board.json`. Every time you read it, Threlmark cross-checks the actual items in `items/`. Missing or misplaced cards are automatically corrected. It’s like having a smart assistant that keeps your project tidy without manual cleanup.

This self-healing property ensures that your view always matches reality, even if files get moved or corrupted unexpectedly.

Practical tips for building with a file-based, local-first mindset

• Use atomic write functions to prevent corruption during crashes.
• Keep each item in its own JSON file for collision-free updates.
• Separate metadata like lane order into dedicated files for easy management.
• Implement read-merge-write cycles to normalize and preserve data.
• Leverage file diff and version control to track changes over time.

How Threlmark’s approach compares to traditional client-server apps

Feature	Threlmark (File-Based)	Traditional Client-Server
Data Source	JSON files on disk	Remote database/API
Offline Capability	Full offline support	Limited; often requires sync layer
Sync Method	Manual or automated file sync	Network requests and conflict resolution
Debugging	Inspect files directly	Use database tools or logs
Scalability	Simpler for small to medium projects	Better for large, multi-user systems

Handling conflicts and ensuring consistency in a local-first system

Threlmark’s system handles conflicts by last-write-wins and version comparison. When two devices change the same card simultaneously, the file with the latest `updatedAt` timestamp becomes the authoritative version. If needed, manual merging is straightforward. Discover how conflict resolution works in local-first systems.

For example, if your laptop and tablet both update a task, you can easily spot the conflict by comparing timestamps and decide which change to keep.

Offline mode and later sync: how Threlmark keeps working smoothly

Because all data is stored locally in JSON files, you can work offline indefinitely. Changes are saved instantly, and sync happens later when connected. This means no interruptions, even in low or no connectivity zones.

When you reconnect, Threlmark can quickly propagate all your local changes to other devices or tools, maintaining a seamless workflow.

The future of local-first apps: simpler, more flexible, more resilient

Threlmark’s design shows that you don’t need a complex database to build powerful apps. By treating disk files as the contract, developers gain transparency, ease of debugging, and flexibility. It’s a straightforward way to support collaboration, automation, and offline work in a single package.

This approach is gaining momentum as more tools embrace local-first principles, making your data more resilient and your workflows more adaptable.

Frequently Asked Questions

What does ‘disk is the contract’ mean in practice?

It means the JSON files on your disk are the single source of truth. Your app reads and writes directly to these files, making the data transparent, portable, and easy to manage without a database.

How does Threlmark handle sync between devices?

Sync happens by copying files between devices. Changes are atomic, conflicts are resolved by timestamps or manual merge, and the architecture supports offline work without issues.

What happens if two devices edit the same card at once?

Threlmark compares the `updatedAt` timestamps and applies last-write-wins. Conflicts are simple to detect and resolve, keeping data consistent without complex protocols.

Is this approach suitable for large, multi-user apps?

It works well for small to medium projects where simplicity and offline support matter most. Larger, multi-user systems might require a more robust, server-based solution.

Can I manually inspect and migrate my data?

Absolutely. Since data lives in plain JSON files, you can open, edit, and migrate your data with any text editor or version control system.

Conclusion

Threlmark’s approach proves that a simple, transparent architecture built around the disk as the contract can unlock powerful, flexible workflows. It’s a reminder that sometimes, the simplest tools — plain files — can create the most resilient systems.

Next time you think about your app’s architecture, ask yourself: could the disk itself be the contract? The answer might just be yes — and it might make your life easier, too.