Imagine your project management tool could work just like that: no server, no cloud, yet it keeps track of everything perfectly. Learn more about local-first architecture. Sounds like magic, right? But it’s actually a deliberate design choice in Threlmark’s local-first architecture. Here, your disk becomes the single source of truth, making your data more resilient, private, and portable than any cloud service could offer.

In this article, you’ll see how this simple yet powerful idea shapes the entire system — from how data is stored and synchronized, to how external tools participate, and why this approach could redefine how you build and think about apps.

Key Takeaways

• Treat your disk layout as the API: plain JSON files define your entire system, making data portable and inspectable.
• Atomic file writes prevent corruption, ensuring safe concurrent edits without locks.
• One file per item enables collision-free updates and simplifies concurrency management.
• The system self-heals: lane order and project structure are dynamically reconstructed from existing files.
• External tools and AI agents can participate naturally because data lives in plain, readable files.

How Disk as the Contract Changes Everything

Using the disk as the primary contract means the on-disk layout *is* the API. Every piece of data lives in plain JSON files, which anyone can read, modify, or sync. Think of it as a shared, human-readable database that’s also the ultimate authority.

For example, instead of a centralized server dictating what your project looks like, your files — like threlmark.json and items/123.json — define the entire system. This makes data portable, inspectable, and safe from vendor lock-in. You can read more about how disk as the contract impacts system design here.

It’s like leaving a trail of breadcrumbs you can follow, share, or migrate—no special tools needed. This simplicity unlocks powerful benefits: easy backup, cross-platform compatibility, and the ability for external tools to participate without permission.

Step-by-Step: How Threlmark Stores and Syncs Data

1. Data lives in files. Each project gets its own folder, with one file per card. This breaks the race condition of bulk JSON lists, making concurrent edits safe.
2. Atomic writes prevent corruption. Files are written via temp files and renamed instantly, so you never get half-written data.
3. Self-healing board. The lane order isn’t stored in a single list but is dynamically reconstructed from the current items, so the system automatically corrects itself if files go missing or get out of sync.
4. External tools participate easily. Drop a new card into the folder, and the system recognizes it immediately. No need for API calls or server-side validation. External tools can participate easily because data lives in plain, readable files.

By following these steps, Threlmark keeps data consistent, safe, and highly flexible.

Why Local Storage Makes Your App Resilient and Private

Local storage isn’t just about offline work — it’s about ownership. When your data lives on your device, you’re in control. No vendor can lock you out or delete your data without your permission.

Take an example: imagine working on a project during a flight, with no internet. Your data remains fully accessible, and when you reconnect, synchronization happens seamlessly. Plus, your data is shielded from prying eyes if stored securely on disk.

Recent research shows that local-first systems inherently boost privacy, since data doesn’t need to traverse the cloud unless explicitly shared. This approach also reduces backend complexity, saving hours of server maintenance and exposing fewer attack vectors.

How External Tools Join the Local-First Party

Because the data is just plain files, any tool can read or write to your project. Want a script to auto-tag cards? Drop a JSON file into the right folder, and Threlmark recognizes it. Need to generate a report? Just read the files directly.

For example, IdeaClyst, an external AI assistant, can participate without special permissions. It observes the files, suggests updates, and even moves cards to ‘Done.’ All this happens because the core data isn’t locked behind an API but exposed as a human-readable, editable file system.

This openness means your system is truly adaptable — no lock-in, no vendor-specific APIs, just plain files everyone can understand.

Tradeoffs: When Disk-First Might Not Be Enough

While disk as the contract offers many advantages, it’s not a silver bullet. Large projects with hundreds of thousands of files can become slow, and conflict resolution gets tricky with highly concurrent edits.

For instance, real-time multi-user editing might require additional mechanisms like CRDTs or conflict-free replicated data types. Also, syncing over slow networks or with remote devices can introduce latency.

In some cases, a hybrid approach — local-first with optional cloud sync — works best. But the core idea remains valuable: keep the data local, and treat disk as the ultimate authority.

Getting Started with Threlmark and Local-First Principles

If you want to try Threlmark yourself, start by cloning its GitHub repo. Read the source code to see how files are structured. Then experiment with editing JSON files directly, or write scripts to automate updates.

Key tips:

• Use atomic file writes to avoid corruption.
• Keep your folder structure simple and consistent.
• Leverage the self-healing board to keep your lanes aligned.

Remember, the goal is to treat your disk as the single source of truth, making your data portable and resilient.

Frequently Asked Questions

What does ‘disk is the contract’ actually mean?

It means your system’s data lives in plain JSON files on disk, and these files define everything about your app. The files are the source of truth, making your data portable, inspectable, and independent of any server or cloud.

How does Threlmark handle multiple devices syncing changes?

Changes are stored in individual files. When syncing, external tools compare files, apply merges, and update only what’s needed, relying on atomic writes. This approach avoids conflicts and makes the system resilient.

Can this setup support real-time collaboration?

Yes, but it might require additional conflict resolution mechanisms like CRDTs for very high concurrency. The core idea is that local files remain the single source of truth, and syncing happens asynchronously. For more insights into local-first principles, visit Ebus Expert.

What are the main tradeoffs of a disk-first architecture?

It’s excellent for resilience, privacy, and simplicity. But, large projects with many files or real-time multi-user editing may need additional tools or hybrid solutions to handle performance and conflicts.

Is this approach practical for production apps today?

Absolutely. Threlmark and other local-first tools demonstrate that with careful design, disk-based data management is scalable, safe, and ready for real-world use, especially for productivity and project management apps.

Conclusion

By making the disk the contract, Threlmark turns data ownership, resilience, and flexibility into built-in features. This approach simplifies the architecture while empowering users and tools alike.

Imagine a future where your apps are portable, your data is yours alone, and collaboration happens without cloud lock-in. That’s the promise of local-first design — and Threlmark shows it’s not just a theory, but a practical reality.