Imagine a productivity app that keeps working perfectly—even without internet. No lag, no error messages about server timeouts. That’s the promise of Threlmark’s architecture. It’s built on a simple idea: your disk is the contract. The files on your device aren’t just storage—they’re the single source of truth that drives the entire system.

In this article, you’ll learn how this approach transforms the developer experience, boosts resilience, and enables new kinds of collaboration. For more on local-first architecture, see this detailed overview. We’ll explore what “disk is the contract” really means, how Threlmark uses plain JSON files instead of a database, and why this matters for modern apps that want to work offline and sync seamlessly.

Key Takeaways

• Treat the on-disk JSON files as the single source of truth to simplify development and increase reliability.
• Use atomic file writes to prevent corruption and race conditions, enabling safe concurrent updates.
• Design the directory structure to be transparent and portable—backups and sync are just file copies.
• Implement self-healing logic to automatically reconcile and repair data inconsistencies.
• Choose this approach for offline-first, collaborative tools where user control and simplicity matter most.

Why ‘Disk Is the Contract’ Means Your App Works Offline and Smarter

‘Disk is the contract’ is a fancy way to say your app’s data lives on your local device’s storage, not hidden behind a server. It means you can keep working—reading, writing, updating—without waiting for a network. Imagine editing a project on a plane, then resuming where you left off once you land. That’s the power of local-first design.

According to Expo’s local-first guide, this approach makes apps faster, more resilient, and simpler to reason about. It removes the fragile layer of server dependency, letting your device be the source of truth. When connectivity returns, syncing is just a matter of reconciling your local files with others.

How Threlmark Turns Disk Storage into an Instant API

Threlmark’s genius is in its simplicity: the on-disk JSON files are the API. You can learn more about similar architectures in this article. Each card, project, or roadmap is a plain JSON file stored in a well-defined directory structure. When you open your app, it reads these files directly. When you make an update, it writes back to the file system atomically.

This means no server, no database, no complicated sync protocol—just files. For example, every roadmap item lives in items/ as an individual JSON file. The app knows exactly where to find each piece of data, and external tools can read or write files without permission barriers.

The Power of Plain JSON Files and No Database

Using plain JSON files instead of a database might seem odd at first, but it’s a powerful approach discussed in this write-up. But it’s powerful. Files are human-readable, easy to diff, and portable. You can back them up, move them, or sync them with any tool—Dropbox, Syncthing, or even version control.

Threlmark’s architecture relies on each item being a separate JSON file, like individual notes in a notebook. This approach avoids the complexity of traditional databases, reduces lock-in, and makes the data accessible to any language or tool that can read files.

For example, when you want to see what’s changed, you just diff the files. When you want to migrate, you copy the whole folder. This transparency empowers users and developers alike.

Handling Sync, Conflicts, and Collaboration with Files

Syncing in Threlmark is about keeping files consistent across devices. For a deeper dive into local-first sync strategies, see this article. When updates happen, the system merges changes intelligently, preserving unknown fields and avoiding data loss. Think of it like a friendly editor that combines edits without overwriting each other.

When two devices edit the same card offline, the system detects conflicts and can prompt for resolution or do it automatically based on timestamps. This makes collaboration across devices seamless, even in flaky networks.

For example, you could update a task on your laptop while offline, then see that change reflected on your phone once you reconnect—no manual sync needed.

Why Making Each Item a Single File Boosts Concurrency and Safety

Instead of one big list of cards, each item in Threlmark lives in its own JSON file. This tiny change solves race conditions and makes concurrent editing safe. When you update a card, you’re just overwriting one small file, not the whole project.

Imagine a shared Google Doc—editing different parts simultaneously is easy. The same applies here. Because each file is atomic, multiple tools or devices can update different cards without stepping on each other.

This approach is a big win for reliability. If your system crashes, only a few files might be affected, not the entire data set.

Self-Healing and Reconciliation: Keeping Your Board in Sync

The lane order and project status are stored separately in JSON files, which are read and reconciled every time you open the app. If a card disappears or a lane gets out of sync, Threlmark automatically heals the data—no manual intervention needed.

For example, if a card was accidentally deleted or moved, the system detects the mismatch between the files and corrects it on the fly. This self-healing makes your data always consistent and trustworthy.

It’s like having an invisible editor who tidies up your workspace every time you look away.

Practical Tips for Building with File-Based Data

If you’re inspired to try this approach, here are some concrete steps:

1. Design your data as individual JSON files, one per item.
2. Use atomic write patterns—write to a temp file, then rename—to avoid corruption.
3. Keep your directory structure predictable, with separate folders for items, reports, and suggestions.
4. Reconcile stored states on read to handle missing or out-of-sync files.
5. Leverage diff tools to track changes easily and back up your data.

This pattern scales from small projects to complex apps. Learn more about scalable file-based systems at this resource.

When Is This Approach a Good Fit—and When Not

Using disk as the contract shines brightest in scenarios where offline resilience, transparency, and simple sync matter. Think personal productivity, solo tools, or small-team collaboration where lock-in is a concern.

It’s less suited for apps requiring real-time updates to thousands of users or complex querying capabilities. Large-scale databases or high-frequency trading apps, for example, still need traditional backends.

For instance, Threlmark is perfect for a multi-project roadmap that you want to keep portable and accessible offline. But if your app needs instant global sync or complex analytics, a server-backed database might be better.

Frequently Asked Questions

What problem does ‘disk is the contract’ solve?

It ensures your app remains usable offline, reduces complexity, and avoids lock-in by making local storage the definitive source of truth.

How is this different from traditional client-server architecture?

Traditional apps rely on a central server or database; ‘disk is the contract’ makes local files the primary data source, enabling offline work and seamless sync.

Why use files instead of a database?

Files are human-readable, portable, and easy to sync with any tool. They also eliminate lock-in and simplify data management.

How do sync and conflict resolution work?

Changes are merged based on timestamps, and conflicts are automatically resolved or flagged, allowing smooth collaboration across devices.

What happens when two devices edit the same data offline?

The system detects conflicts during sync and can merge or prompt for resolution, keeping your data consistent across devices.

Conclusion

In a world obsessed with servers and databases, Threlmark reminds us that simplicity often wins. By making disk the contract, you build apps that are faster, more resilient, and more flexible. It’s about trusting your local device, not a remote database, to be the ultimate keeper of your data.

So next time you design a tool, ask: could the disk be the contract? You might just find it makes everything easier—and more reliable—than you ever imagined.