If you’ve ever used a project management app that feels sluggish offline or breaks when the internet drops, you’re not alone. Threlmark takes a radically different route. Instead of a cloud database, it uses plain JSON files on your disk as the system’s heartbeat.

This approach isn’t just about storage—it’s a fundamental shift in how apps think about reliability, sync, and control. It’s a promise that your work is safe, portable, and accessible even when offline. Today, we’re peeling back the curtain on how this architecture works and why it might be the future of local-first software.

Key Takeaways

• Model your app’s state with one JSON file per item to improve concurrency safety and simplify sync.
• Treat the disk as the system’s authority—files are the durable, inspectable source of truth.
• Atomic file writes prevent corruption, ensuring your data is safe during crashes or power failures.
• Folder structure with dedicated zones makes multi-device sync straightforward and reliable.
• Local-first architecture boosts speed, resilience, and offline capability—perfect for modern, distributed workflows.

What ‘disk is the contract’ really means for your data

When Threlmark says ‘disk is the contract,’ it means the files on your disk aren’t just storage—they’re the system’s authority. Every project, card, and update lives as a JSON file, which any tool can read or write. This makes the data transparent and inspectable, unlike opaque databases.

Imagine opening a folder of JSON files. You see your roadmap, each task as its own file. Changes made here are immediately the real data—no waiting for server sync or complex transactions. It’s a simple, reliable contract that everyone respects.

Why does this matter? Because it shifts the entire architecture from a reliance on external systems to one rooted in the local filesystem. This approach reduces complexity, increases transparency, and allows users and developers to understand exactly what data exists at any moment. However, it also means that ensuring data consistency and managing concurrent edits become critical, as all authority resides on the disk. The tradeoff is that developers must implement careful change management and conflict resolution strategies to prevent data corruption or inconsistency, especially in multi-device scenarios.

How modeling with JSON files makes your app more resilient

JSON on disk isn’t just human-readable—it’s a shield against failures. If the network drops or the server crashes, your data stays intact on your machine. You continue working without interruption. When connectivity returns, sync happens in the background.

For example, if your laptop runs out of battery mid-sync, your files remain safe. When you plug back in, Threlmark safely merges changes, avoiding conflicts thanks to atomic file writes.

But beyond simple resilience, this design fundamentally changes the way apps handle failure modes. Since all data is local, the app can operate fully offline, and the risk of data loss due to server outages or network issues diminishes dramatically. The tradeoff, however, is that local data must be carefully managed to prevent corruption—atomic writes are essential, but developers must also consider how to handle incomplete or conflicting data states. This model prioritizes durability but requires robust conflict detection and resolution mechanisms to maintain data integrity across devices and sessions.

Why one file per item beats big JSON arrays every time

Instead of a giant `roadmap.json`, Threlmark creates a separate JSON file for each task. This reduces race conditions and makes concurrent editing safer.

Imagine two people updating different cards at once. With one big file, conflicts can crop up, requiring complex merging. But with one file per item, each change is atomic and isolated, simplifying conflict resolution and reducing the chances of data corruption.

This approach also improves performance because smaller files are quicker to read, write, and sync. It allows for more granular control over updates and makes it easier to implement features like partial syncs or selective refreshes. However, managing a large number of files introduces its own complexity—developers need to handle file enumeration, path management, and potential filesystem limitations. The tradeoff is a more scalable, conflict-resistant system that favors modularity over monolithic data structures.

How the file structure makes syncing and collaboration a breeze

Threlmark’s folder layout isn’t just tidy—it’s a contract for multi-device sync. Files like `items/`, `handoffs/`, and `reports/` are separate zones for different kinds of data. This modular approach means changes in one area don’t break others.

Say you’re working on a task on your laptop and switch to your phone. The app syncs files in the background—no conflicts, no confusion. External tools can also tap into this structure without permission hurdles.

By keeping each piece of data in its own file, sync becomes a matter of copying files—fast, simple, reliable. This design allows for incremental updates, where only changed files are transferred, reducing bandwidth and sync times. It also enables offline edits to be integrated seamlessly once reconnected. The tradeoff is that maintaining consistency across many files requires careful coordination, especially when multiple devices are updating the same data. Nonetheless, this structure leverages the filesystem’s native strengths to create a robust, scalable sync process that aligns well with real-world workflows.

Handling conflicts and merging like a pro

Conflicts are inevitable in multi-device setups. Threlmark handles them with a straightforward approach: last-write wins, but with a twist. The system merges changes intelligently, preserving unknown fields and respecting the existing data structure.

For instance, if two devices update the same task differently, the latest change overwrites, but no data is lost—extra fields are preserved, and the user is notified. This merge strategy keeps the data forward-compatible and safe from corruption.

Atomic file writes are crucial here—they ensure that each update is complete and consistent, preventing partial writes from corrupting data. This approach simplifies conflict resolution because the system can rely on the atomicity of file operations to maintain data integrity during merges, even in the face of unexpected crashes or interruptions. The tradeoff is that conflicts may still require user intervention or sophisticated merging algorithms, but atomic writes dramatically reduce the risk of corruption and inconsistent states.

Making data safe and recoverable during file mishaps

Accidents happen—files get corrupted, power spikes hit, disks fail. Threlmark’s use of atomic writes and a tolerant read-merge cycle keeps data safe even during crashes.

For example, the app writes a temp file then renames it—if a crash occurs mid-write, the original remains untouched. During startup, it can detect incomplete files and roll back or repair.

This resilience isn’t just about preventing data loss; it also facilitates recovery. By maintaining backup copies or versioned files, the system can restore previous states if corruption is detected. The tradeoff involves additional storage overhead and complexity in managing multiple file versions, but this investment ensures that your data remains recoverable and trustworthy even in the worst-case scenarios.

How local-first architecture boosts your productivity

Using local files as the source of truth makes apps feel snappier. No waiting for server round-trips—your interactions are instant. When you update a task, you see it right away, even offline.

Plus, background sync keeps your data current across devices. It’s the difference between a sluggish cloud app and a snappy local-first experience.

Threlmark’s design also reduces complexity—no need to handle offline states, errors, or retries, because the app always has a local copy.

This approach ultimately shifts the user experience from one constrained by network latency to one that prioritizes immediate feedback and seamless offline work. The tradeoff is that developers must handle synchronization conflicts and ensure consistency across devices, which can add complexity. Nonetheless, the benefits in perceived speed and reliability make local-first architecture a compelling choice for modern, distributed workflows.

Tools and frameworks making local-first possible

Many modern tools support this style. Libraries like `fs` in Node.js make file management straightforward. The idea of treating files as the database is gaining traction with projects like [Threlmark](https://github.com/MeyerThorsten/threlmark) and others embracing JSON-on-disk.

Plus, background sync and conflict resolution are handled by custom code, but frameworks like [Thorsten Meyer’s work](https://thorstenmeyerai.com/) show how to build resilient, offline-capable apps.

Ultimately, the trend is toward simple, transparent, and durable systems—where the disk is the contract.

Developers should consider the tradeoffs of this approach, including managing many files, ensuring atomicity, and handling conflict resolution logic. While it simplifies deployment and debugging, it also demands careful design to prevent data corruption and to support seamless multi-device synchronization. The ecosystem is evolving, with new tools and best practices emerging to make this approach more accessible and robust.

Frequently Asked Questions

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

It means the files on your disk are the real record of your data. Instead of a remote database, your app reads and writes JSON files directly, making everything transparent and reliable.

How does this differ from traditional client-server apps?

Traditional apps rely on a central server to store data, which can introduce delays or outages. Threlmark’s approach keeps data local, syncing changes in the background, so you can work offline and be confident your info is safe.

Why use JSON files instead of a database?

JSON files are simple, portable, and easy to inspect. They let you see exactly what’s stored, make manual edits if needed, and avoid lock-in or complex setups common with databases.

How does syncing work when multiple devices edit the same data?

Changes are stored as individual files, and the system merges updates intelligently. Atomic writes and a clear folder structure help prevent conflicts and keep everything consistent.

What happens during offline mode or server outages?

Your data remains accessible on your device. You continue working normally, and when the connection comes back, changes sync automatically with no fuss.

Conclusion

The idea that ‘disk is the contract’ turns the traditional client-server model on its head. It’s a simple, honest way to build apps that are faster, more reliable, and less dependent on network conditions. When your data lives right on your device, you gain control, peace of mind, and a smoother experience.

Next time you start a project, ask yourself: could your app run just as well—if not better—by making the disk the system’s heart? Sometimes, the most straightforward design is also the most powerful.