Imagine working on your project roadmap during a flight, without Wi-Fi. Learn more about offline productivity tools. Changes you make are instantly saved locally, and when you reconnect, everything syncs seamlessly. That’s the core idea behind Threlmark’s approach: the disk is the contract.

This architecture flips traditional client-server models on their head. Instead of relying on a central database, every file on your disk becomes part of a living, portable record. It’s a simple, powerful way to keep your work safe, accessible, and flexible—no matter where you are or what device you’re using.

Key Takeaways

• Treat the disk as the ultimate source of truth to simplify sync and increase reliability.
• Use one file per item to avoid race conditions and make external updates safer.
• Atomic file operations prevent corruption even during crashes or power failures.
• Regular self-healing of project views keeps your data consistent without manual intervention.
• A plain JSON file system makes your data portable, accessible, and easy to integrate.

What does ‘disk is the contract’ actually mean?

“Disk is the contract” means your app’s source of truth is stored directly on your device’s disk. When you save a card or update a roadmap, those changes land in JSON files sitting right there on your computer or phone. This isn’t just a backup—it’s the system’s heartbeat.

By anchoring the data directly to your disk, the system ensures that what you see is always the most current and authoritative version. This approach reduces reliance on external servers or cloud services, which can introduce latency, outages, or synchronization conflicts. You can explore related concepts in local-first architecture. Instead, your device becomes a self-sufficient unit, capable of functioning fully offline. The tradeoff is that without a central server, you need to manage synchronization explicitly—using tools or processes you control. But this tradeoff grants you greater control, privacy, and simplicity, especially for users who prefer or require offline access.

How does local-first design improve your workflow?

Local-first design means you can work offline without missing a beat. Changes happen instantly on your device, and syncing occurs in the background, often automatically. For more on local-first systems, see this detailed article. This setup minimizes disruptions, reduces dependency on network quality, and speeds up your workflow because you’re not waiting for remote servers to respond.

Imagine a developer on a plane: they update a task, add new ideas, and organize their roadmap—all locally. When they land and reconnect, Threlmark seamlessly syncs these changes across devices. This approach not only enhances productivity but also ensures data resilience. If a device fails or loses connection, work isn’t halted; it’s still safe locally, ready to sync once online. The tradeoff is that managing conflicts and ensuring consistency requires careful design, but the benefit is a more robust, flexible workflow that’s less vulnerable to outages or server failures.

Why is a file-per-item approach better than a big JSON list?

File-per-item	Single JSON list
Atomic updates prevent conflicts. Each card can be edited independently, reducing the risk of overwriting others’ changes and making conflict resolution more straightforward.	Updating one item risks overwriting others, especially if multiple devices are involved. Race conditions become more likely, leading to potential data loss or inconsistency.
Easy to drop or update a single card without reading the whole list, which improves performance and reduces complexity when working with large datasets.	Requires reading, merging, and rewriting the entire list for each change, which can be slow and error-prone as data grows.
Collision-free with atomic `rename()` writes ensures each update is safe and consistent, even when multiple processes modify files simultaneously.	Collisions can corrupt data if multiple writers happen at once, making manual conflict resolution necessary and complicating synchronization.
Self-healing board state. When files are added, removed, or reordered, the system can automatically reconcile discrepancies, maintaining consistency without manual effort.	Manual reconciliation is often needed if files go missing or become out of sync, which can be tedious and error-prone.

Choosing a file-per-item model means your system is more resilient, easier to scale, and better suited for multi-user environments. Discover more about local-first data management. It reduces the complexity of conflict resolution and makes external modifications safer, enabling smoother collaboration and integration.

Frequently Asked Questions

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

It means your app’s data lives directly on your device’s disk as JSON files. Changes are saved locally, and the files serve as the definitive record, simplifying sync and avoiding reliance on centralized databases.

How does Threlmark handle conflicts when two devices edit the same card offline?

Threlmark’s file-per-item approach minimizes conflicts by isolating changes to individual files. When conflicts do occur, the system defaults to last-writer-wins, but you can implement custom merge strategies. This design reduces the risk of data corruption and makes conflict resolution more manageable, ensuring that your data remains consistent and trustworthy even in complex multi-device scenarios.

Is local-first architecture more reliable than cloud-based systems?

Yes, because it allows continuous work without network dependency. Your data remains accessible and consistent, even during outages. Sync happens in the background, making your workflow more resilient and giving you greater control over your data. While cloud systems can offer additional redundancy, the local-first approach prioritizes immediate access and independence, which can be crucial in many workflows.

How do external tools participate in this setup?

Since all data is plain JSON, any tool that can read or write JSON can interact with your project files. Learn how to extend your workflow at Spectralore. This openness fosters automation, integration, and experimentation—whether you’re scripting cleanup, importing data, or building custom views. It empowers you to extend and adapt your system without vendor lock-in or proprietary formats.

Conclusion

When you treat the disk as the contract, you gain a system that’s simple, resilient, and flexible. For more insights, visit LookAtWorth. It puts control back into your hands—no server required.

Imagine your data as a set of well-behaved files, always honest and ready to move with you. That’s the core insight behind Threlmark’s approach. Now, ask yourself: what if your next project was built on this kind of trust?