Imagine a project tool that doesn’t rely on a cloud or a server. It’s all on your disk. It’s all on your disk. That’s the core idea behind Threlmark’s local-first architecture. Instead of storing data in a database, every piece of information lives as a file. This creates a system that’s simple, resilient, and easy to integrate with other tools. If your computer crashes or you switch devices, your data stays safe and accessible. In this deep dive, I’ll show you exactly how this disk-as-the-contract approach works—and why it’s a game-changer for productivity and collaboration. We’ll explore the mechanics, the benefits, and how it all fits together. Ready to see how a single folder full of JSON files can power a full project management system?

Key Takeaways

• Treat the disk as the single source of truth—no database needed, just plain JSON files.
• Use one file per item to prevent race conditions and make updates atomic.
• Implement atomic writes by writing to a temp file then renaming, ensuring data safety.
• Design self-healing structures that reconcile and clean up automatically on each read.
• Sync changes by comparing file hashes and timestamps, resolving conflicts predictably.

What ‘disk is the contract’ really means in Threlmark

At its core, ‘disk is the contract’ means that the entire system’s state is stored in files on your disk. There’s no central server or database dictating the truth. Instead, your files are the source of truth, and every tool — whether it’s the app or an external script — reads or writes directly to these files.

Understanding this is crucial because it shifts the perspective from traditional centralized systems. Instead of relying on a server to maintain consistency, the system depends on the integrity of the files on your disk. This means that the reliability of your data hinges on proper file management—atomic writes, backups, and conflict resolution become vital. The advantage is that this approach makes the data inherently portable; you can move, copy, or back up your entire project simply by copying files. The tradeoff, however, is that managing consistency and synchronization requires careful design, since there’s no single source controlling the state. This decentralization empowers users with greater control and transparency but demands discipline in handling concurrent changes and conflicts.

How local-first architecture differs from traditional cloud apps

Feature	Traditional Cloud Apps	Threlmark’s Local-First
Data storage	Server-side database	Local JSON files on disk
Offline work	Limited, syncs later	Full offline capability
Syncing	Background, often complex	Manual or automatic file-based sync
Resilience	Dependent on server availability	Works entirely offline
Portability	Limited, tied to platform

The mechanics of syncing and conflict resolution

Syncing in Threlmark is built into the design—files are the protocol. When devices connect, they compare file modification timestamps and hashes. Changes are merged intelligently, preserving unknown fields to stay compatible. Conflicts are resolved based on timestamps or user intervention.

Understanding this process is important because it highlights the balance between simplicity and robustness. By relying on file hashes and timestamps, the system can quickly detect changes without complex state tracking. This enables a straightforward conflict resolution process—either automatically favoring the latest change or prompting the user to decide. The tradeoff here is that, while this approach is reliable for many scenarios, it may struggle with extremely high concurrency or complex merges. Nonetheless, for most typical use cases, this file-based sync offers a reliable and transparent way to keep multiple devices in sync, making conflicts predictable and manageable.

Why one file per item makes everything safer and faster

Instead of a big JSON array for all cards, Threlmark uses one file per item. This prevents race conditions and makes updates atomic. When a change happens, only one file is touched, so external tools can safely update individual cards without locking or coordination.

This design choice is significant because it reduces the risk of data corruption and simplifies recovery. If a file gets corrupted, only that specific item is affected, and restoring it is straightforward—just replace or revert that file. Speed-wise, updating individual files is faster because it avoids rewriting large datasets, and atomic writes ensure that partial updates don’t leave the data in an inconsistent state. The tradeoff is that managing many small files can become complex at scale, but for most projects, this approach offers a clear advantage in safety and speed, especially when combined with proper version control and backups.

How the system heals itself and keeps the board in sync

Threlmark’s board isn’t just a static list; it’s a self-healing structure. Every time you read the board, it compares the list of item IDs to the actual files in `items/`. Missing or orphaned IDs are cleaned up automatically, ensuring the visual representation reflects the true state of your data.

This process is crucial because it maintains consistency without manual intervention. If a file is deleted or corrupted, the system detects discrepancies during the next sync and corrects them—either by removing orphaned IDs or flagging issues for review. This auto-healing capability reduces manual maintenance and prevents inconsistencies from snowballing, which can be common in decentralized systems. It also means that even if external tools or accidental deletions occur, the system can recover gracefully, maintaining the integrity of your project view over time.

What it takes to build and maintain a disk-first system

Building a disk-first app requires discipline—atomic writes, tolerant merges, and clear folder structure. Threlmark uses a simple pattern: write to a temp file, then rename, to guarantee atomicity. It also merges updates carefully, keeping unknown fields to stay compatible.

Maintaining such a system involves regular backups, version control, and careful handling of external tools to avoid corrupting data. The key is designing processes that respect the file structure and ensure data integrity during concurrent modifications. The advantage is that you avoid the complexity of database migrations and lock management—your entire system remains transparent and portable. However, it demands consistent discipline and good practices, especially as the project scales. If managed well, it offers a resilient, flexible foundation for a variety of workflows.

Real-world example: Threlmark in action

Imagine a team using Threlmark to manage multiple projects. Each project has its own folder with JSON files for cards, boards, and dependencies. They work offline, move cards around, and add new ideas on the fly.

When they reconnect, the system syncs changes across devices—conflicts are resolved automatically or flagged for review. They even use external scripts to analyze data or generate reports by reading the same files.

This setup means their project stays alive and consistent, whether they’re in the office or on the road, with no server dependency.

Frequently Asked Questions

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

It means your data is stored directly as files on your disk, and these files are the single source of truth. No server or database controls the state—everything is simply read and written from the filesystem.

How does Threlmark handle syncing across devices?

It compares file hashes and modification times to detect changes, then merges updates while preserving unknown fields. Conflicts are resolved automatically or flagged for manual review, making multi-device workflow smooth.

Can I recover data if a file gets corrupted?

Yes. Since each item is one file, corruption impacts only that piece. You can inspect or revert individual files easily, and backups or version control help restore lost data.

Is this approach suitable for real-time collaboration?

It can be, especially with careful conflict resolution and sync strategies. However, for highly concurrent editing, additional mechanisms may be needed to handle simultaneous changes.

Conclusion

Threlmark’s disk-is-the-contract approach proves that simplicity beats complexity. By making your data files the ultimate record, you gain transparency, portability, and resilience. Whether you’re managing personal projects or collaborating across devices, this architecture keeps your work safe, accessible, and easy to extend. The next time you think about data storage, remember: sometimes, the simplest solution is the smartest.