Imagine a project tool that doesn’t lock you into a cloud service or a proprietary database. Instead, it uses plain JSON files on your disk as its brain. That’s the core idea behind Threlmark’s local-first architecture. It’s a surprisingly simple concept that flips how we think about data management — the disk is the contract.

This approach makes your project data immediately accessible, easy to back up, and open to any tool that can read or write files. No server, no API, no vendor lock-in. If you’ve ever lost work in a cloud app during an outage, you’ll appreciate how Threlmark’s design keeps your data safe and portable. Here’s the deep dive into how this architecture works and why it matters.

Key Takeaways

• Treat your filesystem as the primary source of truth — each item as a separate JSON file for transparency and control.
• Atomic file operations prevent corruption and ensure safe concurrent edits, even offline.
• Plain JSON files make data portable, inspectable, and easy to migrate or extend without vendor lock-in.
• Conflict resolution is simpler in a file system — compare, merge, and resolve conflicts with versioning tools like Git.
• This architecture favors small to medium projects that benefit from simplicity, flexibility, and offline resilience.

What Does ‘Disk Is the Contract’ Really Mean?

At its heart, ‘disk is the contract’ means your data lives directly on your filesystem. The JSON files, folders, and their structure define what the system knows about your projects. It’s not just storage; it’s the source of truth. When you open Threlmark, it reads these files directly — no API call needed.

For example, each roadmap card is a separate JSON file in the items/ folder. That card’s data, history, status, and links are all stored in that single file. If you copy that file somewhere else, or back it up, you’ve already duplicated the entire piece of data — no database dump required.

This approach makes the data transparent. You can open a card in your editor, see its details, and even edit it manually if needed. It’s a simple yet powerful way to keep the system honest and flexible.

How Threlmark Handles Offline Edits and Syncing

Threlmark is built for offline-first work. When you make changes, they’re written directly to the JSON files on your disk. These updates are atomic — meaning they’re either fully written or not at all, avoiding corruption.

Suppose you edit a task card while offline. When you reconnect, the system detects changes and can sync them with other devices or tools. Since each item is a separate file, conflicts are easier to manage than in monolithic databases.

For syncing, Threlmark relies on standard file operations. You can back up your entire workspace by copying the folder. When multiple devices modify the same file, the system can handle conflicts by versioning or user intervention, much like resolving merge conflicts in Git.

Why JSON Files Make Data Portable, Inspectable, and Interoperable

Plain JSON files are the secret sauce of Threlmark. They’re human-readable, easy to diff, and can be imported into any tool that understands JSON. This makes the data inherently portable and open.

For instance, you can migrate your roadmap to another tool just by copying the files. Or, you can inspect the data with a simple command like cat or grep. If you want to build custom reports or integrations, just read or write the files directly.

This openness contrasts sharply with traditional databases, which hide data behind APIs and proprietary formats. Threlmark’s choice empowers you to control your own data, avoiding vendor lock-in and ensuring long-term access.

Comparison: Files vs. Databases — Which Fits Your Workflow?

Feature	File-Based (Threlmark)	Database-Backed
Portability	High — just copy files	Low — requires specific export/import tools
Inspectability	Easy — human-readable JSON	Harder — opaque binary or SQL dumps
Offline work	Seamless — files are local	Complex — usually needs sync layer
Conflict resolution	Simple — file merge, versioning	Complex — transaction conflicts, locks
Scalability	Good for small to medium	High — handles large datasets better

For small teams or personal projects, file-based systems like Threlmark are fast, transparent, and easy to manage. Larger, collaborative systems might prefer databases. The choice depends on your needs.

Keeping Data Safe with Atomic Writes and Tolerant Merging

Data safety in a file-based system hinges on atomic writes and tolerant merging. Threlmark writes files atomically — first to a temporary file, then renaming it. This prevents corruption if your system crashes mid-save. Learn more about local-first architecture.

When updating, it reads the current file, merges changes, and writes back. This process preserves unknown fields and defaults, making the system resilient to version changes and extensions. It’s like carefully editing a document rather than overwriting it blindly.

For example, if a new feature adds a field to a card, older versions of Threlmark will ignore the extra data, but won’t break when reading or writing the file. That forward-compatibility keeps your data safe over time.

What Happens When Multiple Devices Edit the Same Data?

Multiple devices can edit files independently, but conflicts can happen. Threlmark handles this by detecting differences and offering merge options or conflict markers, similar to Git.

Imagine editing a task on your laptop and your phone at the same time. When you sync, Threlmark compares file versions and prompts you to resolve conflicts. Since each item is a separate file, the process remains straightforward.

This approach avoids the dreaded data loss common in many sync systems. It also encourages cautious editing, knowing that conflicts are manageable.

Why Not Use a Traditional Database? Pros and Cons

Traditional databases centralize data, offering speed and scalability. But they hide your data behind APIs and schemas, making backups and migrations harder. They also require server setup and ongoing maintenance.

Threlmark’s JSON files are simple, transparent, and portable. You can back up your entire system by copying a folder. Plus, you can open a file in your editor to see exactly what’s stored.

However, file-based systems may struggle with high concurrency or very large datasets. For small teams or solo projects, the simplicity outweighs the scalability concerns. It’s a trade-off: transparency and ease versus raw power.

Practical Tips for Adopting a Disk-First Approach

1. Start with clear file naming conventions and directory structure.
2. Write atomic functions for all file operations.
3. Use merge strategies that preserve unknown data and defaults.
4. Regularly back up your data folder — it’s your whole system.
5. Test conflict handling in multi-device workflows early.
6. Leverage JSON’s human-readability to debug and extend your system.
7. Document your file structure and data schema for future you.

For example, Threlmark’s GitHub repo shows how atomic write functions keep data safe and reliable.

Frequently Asked Questions

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

It means your data lives directly on your filesystem as JSON files, which serve as the single source of truth. Any tool or script can read, write, and back up your data just by interacting with those files.

Is the app truly offline-first, or just partially functional offline?

Threlmark is designed for full offline use. Edits happen locally in files, and syncing occurs smoothly when back online. This ensures continuous productivity without relying on a remote server.

How are JSON files structured in Threlmark?

Each project card gets its own JSON file in the ‘items/’ folder, containing all relevant data like status, links, and history. Additional files manage project metadata, relationships, and sync states.

How does syncing avoid data loss when multiple devices edit the same files?

Threlmark detects differences via file comparison, then prompts conflict resolution. Because each item is a separate file, conflicts are easier to manage than in monolithic databases.

Why not use a traditional database instead of files?

Databases offer scalability but hide your data behind APIs and schemas, complicating backups and migrations. Files are transparent, easy to back up, and open to any tool that can handle JSON.

Conclusion

When you put the disk at the center of your data model, you gain control and clarity. Threlmark’s approach shows that complexity doesn’t have to come from fancy databases — it’s embedded in how you treat your files.

If you want a project system that’s transparent, portable, and resilient, consider how storing everything as JSON files on disk can change your game. Sometimes, simplicity is the smartest choice you can make.