Imagine a project management tool that works offline, stores every piece of data as plain files, and never needs a server. That’s the promise behind Threlmark’s mission — and it’s more than just a gimmick. Disk is the contract. It’s a shift in how we think about managing data, moving from cloud-centric databases to a simple, resilient disk-based system.

What makes this approach so compelling? It’s the core idea that the disk isn’t just a place to save data — it’s the contract. Every file, every folder, every JSON snapshot forms the living record of your work. No lock-in, no complex sync protocols, just straightforward file operations.

In this article, I’ll walk you through how Threlmark’s local-first architecture works, why it’s powerful, and what it means for your projects.

Key Takeaways

• Using the disk as the contract makes your data portable, inspectable, and safe from cloud dependencies.
• Atomic file writes and tolerant merge updates prevent corruption and support forward compatibility.
• Small, individual JSON files facilitate conflict resolution, offline work, and multi-device sync.
• A folder-based structure simplifies backups, migrations, and external integrations.
• While powerful, this approach requires good conflict handling and security practices for larger or sensitive projects.

What Does ‘Disk Is the Contract’ Actually Mean?

“Disk is the contract” means that all the data’s truth lives in files on your local disk, not in a remote database. When you open Threlmark, it reads from a set of JSON files, and that’s where the entire state lives. It’s like your project’s notebook — every note, task, and link stored as a plain text file.

For example, when you update a task, Threlmark writes a new JSON file for that card. The next time you open the app, it reads that file, sees the latest info, and displays it. If you copy that file somewhere else, you’ve basically moved or shared that piece of your project.

This approach makes data transparent, easy to back up, and simple to move around.

Why Threlmark Prefers Files Over Databases

Threlmark chooses files instead of a database because files are inherently portable and inspectable. Unlike a cloud database, files can be copied, backed up, and inspected without special tools. You can open a JSON file in any editor, see exactly what it contains, and trust it’s accurate.

Let’s compare: a database hides your data behind a service, making it harder to see or move. Files, on the other hand, are just plain text that you can manipulate with your tools of choice.

Feature	Database	Files
Portability	Requires export/import or sync tools	Copy files directly
Inspectability	Requires special tools or UI	Open in any text editor
Lock-in	High, depends on provider	Low, just files

How Threlmark Keeps Data Safe and Consistent with Files

Storing data in files sounds risky, but Threlmark uses two key techniques to stay safe: atomic writes and tolerant merge updates.

Atomic writes mean that every change writes to a temporary file first, then renames it. This avoids corrupting data if your system crashes halfway through. For example, when you save a task, the app writes to `task123.json.tmp` and then renames it to `task123.json`. It’s like sealing a letter before dropping it in the mailbox.

Merge updates mean that when reading a file, Threlmark merges changes instead of overwriting blindly. It keeps track of metadata like `createdAt` and updates `updatedAt`, and it preserves unknown fields. This makes it easy to add new features without breaking older tools and ensures data integrity over time.

How the File Structure Supports Collaboration and Sync

Threlmark’s architecture divides data into many small JSON files, each representing a separate card or project. Every file lives in a dedicated folder, like `items/`, `shared/items/`, or `archive/`. When a team member updates a task, they just overwrite the individual JSON file.

Syncing happens by copying or syncing the entire folder structure. Learn more about Threlmark’s local-first architecture. Because each file is atomic, conflicts are easy to spot — just check which files changed. For example, if two people edit the same task, the last save wins, but you can also manually compare the JSON files to resolve conflicts.

This structure promotes collaboration across devices or even offline work, because everything is stored locally, and sync is just file transfer.

The Real Benefits of a Disk-Based, Local-First System

Choosing disk as the contract yields several clear advantages:

• Portability: Copy your project folder anywhere—Dropbox, USB, another device—and pick up where you left off.
• Transparency: Open files directly to see exactly what data is stored, no hidden layers.
• Resilience: No server downtime or network issues block your work. You stay productive offline.
• Security: Your data stays on your device unless you choose to sync or share.

These benefits make Threlmark ideal for teams that prioritize control, safety, and flexibility.

What Limitations Should You Know About This Approach?

While this design has many perks, it’s not perfect for every scenario. Large projects can make file management cumbersome, and syncing conflicts might get tricky if many devices edit the same file simultaneously. Also, security depends on how well you protect your local files.

For example, if you’re working with a team spread across multiple continents, conflicts might increase, and you’ll need robust sync tools. Plus, without encryption, local files could be vulnerable if someone gains access to your device.

Understanding these limits helps you decide if a disk-based, local-first system suits your project’s scale and security needs.

Practical Tips for Building Your Own File-Based App

If you want to adopt a similar approach, here are quick tips:

1. Use atomic write techniques—write to a temp file, then rename.
2. Keep each data item in its own JSON file for easy updates.
3. Design your folder structure to separate active, shared, and archived data.
4. Merge updates carefully—preserve metadata and unknown fields.
5. Test conflict scenarios early, especially if multiple devices or users will edit files.

These practices will keep your local-first app reliable, maintainable, and easy to scale.

Frequently Asked Questions

What does ‘disk is the contract’ really mean?

It means all your project data lives in files on your local disk. These files are the single source of truth, making your data transparent, portable, and easy to manage without relying on a remote server.

Why choose files over a database for my app?

Files are inherently portable and inspectable. You can copy, back up, and modify them directly. This reduces lock-in and simplifies syncing and troubleshooting, especially for local-first workflows.

How does Threlmark handle conflicts when multiple devices edit the same file?

Threlmark uses small, atomic JSON files so conflicts are easy to detect. When conflicts happen, you compare the files manually or set rules to resolve which change wins, making conflict management straightforward.

Can I still work offline with this system?

Absolutely. Since all data is stored locally as files, you can read, edit, and save your work without any network connection. Sync happens later when you’re online.

Is this approach secure for sensitive data?

Data security depends on how you protect your files. Since everything lives on your device, you control access. But if you sync or share, consider encryption to keep sensitive info safe.

Conclusion

Threlmark shows that the simplest idea — the disk is the contract — can lead to a flexible, resilient, and transparent system. It’s a reminder that sometimes, going back to plain files offers the most control and peace of mind.

If you want a project management system that’s easy to back up, move, and understand, this approach is worth considering. Embrace the power of the file, and your data becomes a true, portable asset, not just a cloud token.