What if your project management app didn’t depend on a server or cloud? Imagine a system that works instantly, even offline, and lets you move your data anywhere without lock-in. That’s the magic of Threlmark’s local-first architecture. It’s a radical rethink that turns your disk into the contract — the single source of truth.

This isn’t just about storage; it’s about building a smarter, more resilient way to coordinate work across devices and tools. In this article, you’ll see how a simple on-disk layout can power a complex, collaborative system that’s fast, flexible, and future-proof.

Key Takeaways

• Threlmark’s core design hinges on the idea that the on-disk layout *is* the API, making data transparent and flexible.
• Atomic file operations ensure data safety even during crashes, avoiding corruption or inconsistency.
• One file per item allows conflict-free updates and simplifies concurrency control.
• Self-healing lane structures keep the project board consistent without manual intervention.
• Local-first architecture boosts speed, offline reliability, and multi-device sync—perfect for mobile and remote workflows.

What does ‘disk is the contract’ really mean? Think simple, stay flexible

“Disk is the contract” means that your data lives on your device, and that’s where all the authority resides. No server, no cloud. Just files in a predictable, structured layout. For example, Threlmark stores each project, card, and relationship as individual JSON files. This setup makes the data transparent and easy to manipulate outside the app.

Imagine editing a project file directly in your text editor. You can see exactly what’s stored, make quick fixes, or move things around. That’s the power of a file-based contract. It’s simple but incredibly flexible.

Why does this matter? Because it shifts the control and understanding of your data from opaque server structures to transparent files you can inspect, modify, and understand directly. This transparency reduces reliance on proprietary systems, making your data more portable and resilient to vendor lock-in. For more on this approach, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture.

Why storing data on disk makes your app faster and more reliable

Local storage means no waiting for network responses. When you open Threlmark, it reads JSON files instantly from your disk. No delays, no loading spinners. That immediate responsiveness feels natural—like working directly on paper. You can learn more about how this architecture enhances performance at Disk Is the Contract.

Plus, if your device crashes or loses internet, your work isn’t lost. Everything is already saved locally. You can keep working, confident that your data is safe on your machine.

But there’s more: this approach reduces dependency on network stability, which is often a bottleneck or point of failure in cloud-based apps. It also allows for true offline work—your data is always accessible, regardless of connectivity. The tradeoff is that local storage alone can complicate synchronization and conflict resolution, especially in multi-user scenarios, but for individual or small-team workflows, the speed and resilience benefits outweigh these challenges.

How Threlmark’s file layout keeps everything portable and interoperable

Threlmark’s folder structure is a detailed contract. At the root, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project gets its own folder with files like `project.json`, `board.json`, and then one file per card under `items/`. This setup allows for easy backup and migration—more details can be found in Disk Is the Contract.

This setup allows you to copy, back up, or move your entire workspace with a simple `cp` or sync. Other tools can read and write these files directly, making integrations straightforward. Want to build your own views or automate updates? Just read or write the JSON files.

Why does this matter? Because having a clear, standardized directory and file structure means your data isn’t locked into a proprietary format or system. It’s inherently portable—easy to back up, migrate, or integrate with other tools. This openness fosters interoperability, giving you flexibility to adapt your workflow or switch tools without losing your data.

How atomic file operations keep your data safe and consistent

Writing to disk might sound risky, but Threlmark uses atomic saves. Each update writes to a temporary file, then renames it over the original. This guarantees that you never end up with a half-written, corrupted file. For more on ensuring data safety, see Disk Is the Contract.

Why is this important? Because in real-world scenarios—power failures, crashes, or interruptions—partial writes can corrupt data, leading to loss or inconsistency. Atomic operations prevent this by ensuring that only fully written files replace the old ones, preserving data integrity.

This pattern is a simple yet powerful safeguard. It guarantees that your project files remain trustworthy even in adverse conditions, reducing the risk of data corruption and making recovery easier when issues occur.

One file per item: how Threlmark avoids conflicts and race conditions

Instead of storing all cards in a big array, Threlmark keeps each card in its own JSON file inside `items/`. This way, external tools can update a single card without touching the rest. Learn more about this approach at Disk Is the Contract.

Imagine two people editing different cards at the same time. Because each file updates independently, they don’t step on each other. This approach eliminates race conditions common in monolithic JSON files, where simultaneous edits can overwrite or corrupt data.

Additionally, this structure simplifies conflict resolution. When the system reads the folder, it can easily detect which files have changed, been added, or deleted, making synchronization more reliable. This setup supports concurrent editing and reduces the risk of data loss, especially in multi-user or multi-device environments.

How the board heals itself: reconciling lane order and card status

The lane order in Threlmark is stored in `board.json`, listing IDs in sequence. When loaded, the system cross-checks the actual files in `items/` and rebuilds the lane order if needed.

This self-healing process is crucial because it allows the system to recover from inconsistencies caused by external modifications or errors. If files are deleted, moved, or corrupted outside the app, the system detects discrepancies and reconstructs the correct order and state based on the available data.

This approach ensures that your visual board remains consistent with the underlying data. It reduces manual correction efforts and prevents display errors, especially after unexpected interruptions or external edits. The tradeoff is a slight overhead during load, but the benefit is a robust, self-correcting system that maintains integrity automatically.

Syncing and conflict resolution: making multi-device work smoothly

Threlmark’s architecture treats sync as a background process. Changes in one device are stored locally, then pushed to other devices when connected. Conflicts are resolved by rules—latest update wins, or manual review.

Why does this matter? Because in multi-device environments, conflicting changes can easily occur. Threlmark’s conflict resolution rules—such as favoring the most recent change or prompting user input—are essential for maintaining data consistency without complex locking mechanisms.

This approach allows seamless multi-device workflows, where each device operates independently yet stays synchronized. The tradeoff is that conflict resolution may require user intervention or predefined rules, but the benefit is a resilient, flexible sync process that doesn’t rely on central servers.

Securing your data: encryption, backups, and device loss

Storing data locally raises security questions. Threlmark can encrypt files or rely on device encryption to keep data safe. Regular backups are simple—just copy your `~/.threlmark` folder.

But why is this important? Because local storage, while fast and resilient, can be vulnerable if not secured properly. Encryption ensures that even if someone gains access to your files, the data remains protected. Regular backups prevent data loss due to hardware failure, theft, or corruption, ensuring you can restore your workspace quickly.

In practice, combining encryption with regular backups and device security measures creates a comprehensive safety net. This layered approach balances speed and control, giving you confidence that your data is both accessible and protected.

When should you choose local-first architecture? Know the tradeoffs

Local-first works best when responsiveness, offline access, and portability matter most. If your team needs instant updates and can’t depend on always-on internet, this is a game-changer.

However, managing sync conflicts and extra device storage are tradeoffs. For large teams or complex data, a server-based approach might still be better.

Use cases include solo projects, small teams, or highly mobile workflows where speed and independence are priority. Understanding these tradeoffs helps you decide whether the benefits of speed, control, and offline capability outweigh the added complexity of sync and conflict management.

Frequently Asked Questions

What does ‘disk is the contract’ mean?

It means that your data lives directly on your device as files, which serve as the single source of truth. No server or cloud is needed for day-to-day work, making the system simple and resilient.

How does syncing work when I have multiple devices?

Changes are stored locally and then synchronized in the background. Conflicts are resolved by rules or manual review, ensuring all devices stay up-to-date without complex locking.

Is local-first secure if data lives on my device?

Yes. You can encrypt your files or rely on device encryption. Backups are simple—just copy your data folder—keeping your information safe even if your device is lost.

When should I choose local-first over server-based apps?

When responsiveness, offline access, or portability outweigh the need for centralized data. It’s ideal for solo work, remote teams, or mobile workflows where speed matters.

Conclusion

Choosing a disk-based, local-first approach isn’t just a technical decision—it’s a philosophy that puts simplicity, control, and speed at the forefront. Threlmark proves that by making your disk the contract, you gain a system that’s inherently resilient and incredibly flexible.

Imagine your next project tool that’s fast, portable, and always available—without locking you into a cloud or a database. That’s the promise of local-first design. Why settle for less?