Imagine a world where your project management tool never loses track of your tasks, even if your internet drops out. No cloud, no server, just your own disk as the ultimate authority. That’s the core idea behind Threlmark’s local-first architecture, where the on-disk layout is the contract that guides everything.

In this article, you’ll see how this simple yet powerful shift unlocks offline capabilities, boosts privacy, and simplifies multi-device workflows. We’ll peel back the layers of Threlmark’s design, showing how a single JSON file per item and a clear directory structure make it all work—without locks, servers, or complex sync engines. Ready to see how disk becomes the contract that drives robust, flexible apps? Let’s go.

Why Making Disk the Boss Changes Everything

In traditional apps, data lives in a database or cloud, acting as the single source of truth. Threlmark flips that script. Here, the disk is the contract—your files are the record, not a database.

This shift means your app reads and writes directly to JSON files on your device. The files are simple, portable, and always in your control. For example, a task card is just items/abc123.json. If you copy that file, you copy the data. No need to sync a database or worry about conflicts in a central store.

Why does this matter? Because it fundamentally changes how data is managed. Relying on files means your app is decoupled from complex backend systems, reducing dependencies and potential points of failure. It also means users have complete ownership over their data—no cloud lock-in, no vendor lock-in. However, this approach also involves tradeoffs: managing consistency and conflicts shifts from the server to the local environment, requiring careful design of merge strategies and conflict resolution. This decentralization empowers resilience and offline work, but it demands a clear understanding of how local changes propagate and synchronize to avoid data divergence or loss.

It’s a practical, no-nonsense approach that makes data resilient and easy to manage. Want to back up? Just copy the files. Need to move to a new device? Sync the files. Threlmark’s design makes local storage the ultimate decision-maker—no cloud required.

How Threlmark Keeps Data Safe and Consistent Using Files

Threlmark uses two simple tricks to keep data safe: atomic writes and merge-friendly updates. Atomic writes mean every time it saves a file, it writes to a temporary file first, then renames it. This way, crashes or interruptions never leave the data half-written.

For example, when updating a task card, it writes to items/abc123.json.tmp then moves it to replace the original. That’s fast, safe, and reliable. Plus, it prevents corruption if your laptop suddenly crashes during a save.

The second trick is read-merge-write. Instead of rewriting the whole list, each card is a separate JSON file. When you update a card, you read its current state, merge your changes (preserving IDs and timestamps), then save atomically. This approach is crucial for conflict avoidance. Imagine two editors working on the same task simultaneously: each reads the current file, makes their changes, and writes back. Thanks to atomic writes, only one write will succeed last, preventing corruption. The merge strategy then helps reconcile any differences, especially when unknown fields or concurrent edits occur. This ensures data integrity and consistency across multiple devices or users, allowing for smooth collaboration without complex locking or version control systems.

In essence, these techniques build a resilient environment where local changes are safe, conflicts are minimized, and data remains consistent—even with concurrent or interrupted edits.

The File Layout That Makes Everything Clear and Portable

Threlmark’s directory structure is a simple map that acts like a contract. At the root, you find threlmark.json and links.json. Each project has its folder with project.json, board.json, and a folder items/ for individual card files.

Shared items live under shared/items/, and completed or archived projects move to archive/. External suggestions land in suggestions/, and reports go into reports/.

This structure makes everything inspectable, portable, and interoperable. Because the layout is explicit and predictable, any tool or user can understand and manipulate the data directly. Want to migrate your data? Copy the entire folder structure. Want to integrate with another system? Read and write the JSON files directly, trusting that the layout defines the contract clearly. This transparency reduces friction, makes debugging easier, and supports future growth by providing a stable foundation for data exchange and extension.

Making File-Based State Safe and Reliable — The Key Techniques

Using files sounds risky, but Threlmark’s disciplined patterns make it safe. First, atomic writes prevent corruption. Second, tolerant read-merge-write updates handle concurrent changes smoothly.

For example, if two external tools try to update the same card at once, the atomic write ensures only one wins, avoiding conflicts or corruption. The tolerant merge preserves unknown fields, so future updates don’t break existing data. This approach minimizes data loss, reduces the risk of conflicts, and ensures smooth operation across multiple devices or tools working concurrently.

By carefully orchestrating these techniques, Threlmark facilitates a robust environment where data integrity is maintained despite interruptions or simultaneous edits. The result is a resilient system that supports offline work, collaborative editing, and future scalability without sacrificing safety or simplicity.

Why This Matters for Developers and Users

For developers, Threlmark’s approach simplifies state management. No database schemas or complex sync logic. Just files—easy to back up, restore, or edit.

For users, it means offline-first access, faster response times, and data that belongs to them. No vendor lock-in, no cloud dependency. Just their own disk as the contract.

Imagine editing a task on a train with no internet. When you reconnect, the files sync seamlessly, and your app updates instantly. This scenario highlights how local-first design prioritizes user autonomy and resilience. Users can continue working uninterrupted, confident that their data remains secure and consistent, even when offline. When connectivity is restored, synchronization is straightforward, ensuring data integrity without complex conflicts or delays. This approach empowers users with control over their data and provides a seamless experience across devices, illustrating the practical benefits of building with disk as the primary contract.

The Big Picture: Sync, Conflict, and Future-Proofing

Threlmark treats sync as a background process—files are the source of truth, and syncing happens later. Conflicts are managed through conflict resolution strategies or CRDTs, but the core idea remains: the local disk always wins.

This setup makes the app resilient. If a device loses connection, work continues locally. When back online, changes sync automatically without losing data or overwriting others’ work.

It’s a pattern that future-proofs your app—any new feature or device can simply read or write files, trusting that the contract is stable. This file-centric approach allows for incremental updates, easy debugging, and flexible integrations, making the system adaptable to evolving needs while maintaining data consistency. The focus on local storage as the authoritative source simplifies the architecture and enhances scalability by removing dependency on centralized servers or complex sync protocols.

What Developers Can Take Away — Building with Disk as the Contract

Start by treating your data as files—not in a database. Use atomic write patterns. Keep each item in its own JSON file. Make the directory structure a clear contract that anyone can read or write.

Use tolerant merge strategies to handle concurrent edits. Keep the focus on local storage first, then sync. This approach reduces complexity, boosts resilience, and makes your app more trustworthy. Recognize that this model shifts some complexity from server-side logic to client-side conflict management. Planning for conflict resolution and merge strategies upfront ensures your app remains robust and user-friendly even in complex collaboration scenarios.

Check out Threlmark’s code on [GitHub](https://github.com/MeyerThorsten/threlmark) for real-world examples. It’s a blueprint for building robust, offline-first apps that own their data—from the ground up.

Key Takeaways: What You Should Remember

• Disk is the contract: on-disk JSON files define the source of truth for every piece of data.
• Atomic writes and merge strategies: keep data safe and concurrent edits conflict-free.
• Folder structure as a contract: a clear layout makes data portable, inspectable, and interoperable.
• Offline-first and resilient: work continues without internet, and sync happens transparently in the background.
• Developer-friendly: fewer dependencies, easier backups, and straightforward data management.

Frequently Asked Questions

What exactly does ‘disk is the contract’ mean?

It means the on-disk JSON files are the definitive source of truth for your app’s data. All reading, writing, and syncs rely on these files, making data management straightforward and portable.

How does Threlmark handle conflicts when multiple devices edit the same data?

Threlmark uses atomic file writes and tolerant merge strategies to resolve conflicts. If two devices change the same card, the last write wins without corrupting data, and unknown fields are preserved for future compatibility.

Can I use Threlmark’s approach for collaborative apps?

Yes, but it requires additional sync and conflict resolution layers. The core idea—disk as the source of truth—supports collaboration by making local changes resilient and easily syncable, especially when combined with CRDTs or version graphs.

What storage technologies does Threlmark rely on?

It primarily uses plain JSON files stored in directories on your device—think filesystem, IndexedDB (in browsers), or local folders on desktop apps. The focus is on simplicity and portability.

Is local-first architecture suitable for large, complex apps?

It can be, especially when designed with clear file structures and conflict handling. The approach scales well for apps needing offline access, privacy, and multi-device sync—like note-taking, project management, or personal knowledge bases.

Conclusion

Threlmark’s design proves that making disk the contract isn’t just a technical choice—it’s a philosophy. It puts control, resilience, and simplicity at the heart of your app. When data lives in plain files, you own it, trust it, and can fix or migrate it with ease.

Thinking of building your next app? Start with the disk as your foundation. It’s a quiet revolution that turns your device into the ultimate data hub—fast, safe, and forever yours.