Imagine a project management tool that works perfectly offline, never loses data, and plays nice with any external tool you throw at it. That’s what Threlmark is doing. Its secret? It treats disk storage not just as a place to save data, but as the source of truth itself.

This approach might sound simple, but it flips traditional app architecture on its head. Instead of a server, database, or cloud dictating your data, your entire system relies on a well-organized set of files on your local disk. Ready to see how this works and why it might just change your view of data management? Let’s dive in.

Key Takeaways

• Treat your disk storage as the ultimate source of truth—every file is part of the contract.
• Use atomic writes and read-merge patterns to keep data safe and forward-compatible.
• Separate each item into its own file to prevent race conditions and simplify concurrency.
• Sync by copying files—no server needed—making offline work seamless and resilient.
• This approach suits personal projects or small teams better than large-scale, real-time apps.

Why Threlmark’s ‘Disk Is the Contract’ Changes Everything

In most apps, the database or server is the ultimate authority. Threlmark says, no. The files on your disk are the real contract. When you open Threlmark, it reads from a folder full of JSON files—each card, project, or link is a separate file. This simple shift means your data is always accessible, portable, and safe from server outages.

For example, if you copy the entire folder onto another machine, Threlmark works just as well. No database migration or cloud sync needed. It’s like carrying your entire project management system on a USB stick—ready to run anywhere.

How the On-Disk Layout Acts Like a Legal Contract

Threlmark’s on-disk structure is more than just a file system—it’s a contract. The root contains a manifest (`threlmark.json`) and links (`links.json`). Each project has its own folder with metadata (`project.json`), lane info (`board.json`), and individual cards (`items/.json`). External suggestions go into `suggestions/`, reports into `reports/`, and shared items are stored in a dedicated folder.

This layout guarantees that every file is inspectable, portable, and interoperable. You can open, edit, or move files without breaking the system—because everything is just files. This makes backups trivial, integrations seamless, and migrations a breeze.

Making File-Based State Safe and Sound

Handling files safely sounds tricky—crashes, partial writes, corruption. Threlmark solves this with two simple patterns. First, **atomic writes**: updates go to a temporary file, then rename() to replace the original. This guarantees no half-written files, even if your system crashes mid-save.

Second, **read-merge-write**: when updating, Threlmark reads the current file, merges changes (preserving IDs and timestamps), and writes atomically again. Plus, it tolerates unknown fields, making the system flexible and future-proof.

One File Per Card: How Threlmark Handles Concurrency

Ever tried updating a giant JSON array? Race conditions. Threlmark’s trick: one file per item. Each card lives in its own `.json`. When an external tool updates a card, it only touches that one file—no conflicts with others.

The folder `items/` holds all cards. The `board.json` manages lane order, but it’s reconciled every time it’s read. If a card is missing, the board heals itself. This design keeps concurrent updates safe and simple.

How Threlmark Synchronizes Without a Server

Threlmark’s sync model is simple—since all data lives on disk, syncing means copying files. When connected to another device, you just copy the entire folder, or sync via Dropbox, Syncthing, or git. Conflicts are handled with the same principles: last write wins or manual merge.

This local-first approach means you can work offline for weeks and still get everything synchronized later. No waiting for server responses, no complicated conflict resolution algorithms. Just straightforward file copying.

Real-World Benefits: Speed, Resilience, and Flexibility

Think about editing a project on a train—no internet needed. Changes are instant, because they’re just local file edits. When you reconnect, files sync with your team or cloud service, updating everyone seamlessly.

And if your device crashes? No problem. The data is safe on disk. You can recover or migrate your entire project in minutes by copying files. It’s like having a portable, resilient project database in your pocket.

Tradeoffs and When Not to Use This Approach

While simple and resilient, this model isn’t perfect for every case. Large-scale apps requiring real-time collaboration or complex querying might struggle. The approach works best for personal projects, small teams, or scenarios where offline access is critical.

For instance, a SaaS app with millions of users or needing instant updates across thousands of devices might need a more traditional client-server setup.

Developer’s Guide: Building with Files, Not Databases

If you want to replicate Threlmark, start with a solid file structure. Use atomic write patterns, keep each entity in its own file, and handle conflicts with read-merge logic. These steps create a system that’s robust, portable, and easy to test.

Check out the [Threlmark GitHub repository](https://github.com/MeyerThorsten/threlmark) for code examples and detailed patterns. Your next app could benefit from this straightforward, resilient approach.

The Future of Local-First: Why It Matters More Than Ever

As connectivity becomes more unreliable and privacy concerns grow, local-first systems like Threlmark are gaining momentum. They promise fast, reliable, and private data handling—no cloud needed.

Imagine managing multiple projects, all stored safely on your device, yet still connected and synchronized with a few clicks. That’s the power of treating disk as the contract—simple, reliable, and future-proof.

Frequently Asked Questions

How does Threlmark handle conflict resolution when multiple devices edit the same card?

Threlmark uses a read-merge approach, preserving IDs and timestamps. When conflicts occur, later writes overwrite earlier ones, but you can implement simple manual merge strategies or more sophisticated conflict resolution if needed.

Can I use Threlmark with cloud sync services like Dropbox or Syncthing?

Absolutely. Threlmark’s file-based system is compatible with any sync service. Just point your cloud folder to your data directory, and your data will stay in sync across devices, with conflicts resolved by your chosen method.

Is this architecture suitable for large teams or real-time collaboration?

For large-scale, real-time apps, this approach might face challenges. While excellent for personal use or small teams, bigger projects often require more complex, server-based solutions for instant updates and querying.

What happens if I lose my device or delete the data folder?

Since all data lives in files, losing the folder means losing everything. Regular backups or external syncing are essential. But restoring is as simple as copying your backup back into place.

Are there existing tools or frameworks that support this kind of architecture?

Yes. Many systems, like GlusterFS for storage, treat disks as the core. For apps, using plain files with atomic operations and careful conflict handling is becoming more popular, especially among offline-first and local-first advocates.

Conclusion

Threlmark’s ‘disk is the contract’ idea isn’t just a technical quirk; it’s a fundamental shift in how we think about data. When storage becomes the entire system’s backbone, everything gets simpler, safer, and more portable.

Next time you build a tool or manage a project, ask yourself: can I make disk my contract? If yes, you’re stepping into a future where your data works for you—offline, everywhere, forever.