Imagine a task management app that doesn’t rely on a cloud server or a complex database. Instead, it lives on your disk, where every change is just a file edit. That’s the bold idea behind Threlmark’s local-first architecture — the disk **is the contract**. It’s a simple, transparent, and powerful way to build apps that work offline, are easy to back up, and can sync across devices with minimal fuss.

If you ever wondered how to make a system that’s both flexible and trustworthy without a giant backend, this article is for you. We’re diving into the design choices that make Threlmark stand out — from how it handles data, concurrency, and evolution, to what it means for your own projects. Let’s explore how a humble folder full of JSON files can become a robust, multi-device hub.

Key Takeaways

• Treat the disk as the ultimate source of truth; your app’s data lives in plain JSON files that define its behavior.
• Use atomic file writes to prevent corruption and ensure crash safety during updates.
• Design for schema evolution by preserving unknown keys, allowing your data structure to grow organically.
• Sync across devices by copying folders, not through complex databases or APIs, simplifying multi-device workflows.
• Leverage the transparency and portability of file-based storage for easier debugging, backup, and migration.

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

At its core, ‘disk is the contract’ means your app’s data lives in plain files — no hidden database. The layout and content of these files define the app’s behavior and interface. For example, in Threlmark, each task is a JSON file in the `items/` folder. The filename is the task ID, and its contents include metadata like status, description, and timestamps.

This setup makes everything transparent. You can open a file in any editor, see exactly what’s stored, and even manually tweak it if needed. It’s a living document everyone can understand and modify. The contract is not a black box; it’s the files on disk. This transparency simplifies debugging, backup, and migration.

Why choose plain JSON files over a traditional database?

JSON files are simple, flexible, and human-readable. Unlike a database, they don’t require complex setup or server infrastructure. Imagine editing a task directly in a text editor, seeing all the data at once — no ORM fuss, no migrations. For more on the benefits of this approach, see CoderFacts.

For example, Threlmark’s `items/.json` files store individual cards, making it effortless to add, modify, or delete one without affecting others. This granular control reduces conflicts and makes sync easier. Plus, JSON’s ubiquity means any tool or language can read or write these files without special connectors.

It’s a deliberate tradeoff: you lose some of the querying power of a database, but gain unmatched simplicity, portability, and resilience — especially offline. According to [1], this approach aligns perfectly with the goals of local-first systems.

How does Threlmark handle syncing across devices?

Syncing is a matter of copying files. Threlmark’s architecture encourages syncing entire folders via Dropbox, Syncthing, or git. Since each item is a separate file, conflicts are minimized, and partial updates are straightforward.

When two devices modify the same task, Threlmark’s system detects conflicts via timestamps or version info stored in files. It then prompts for resolution or applies smart merge strategies. The key is that the source of truth remains on disk, so sync tools just mirror the folder.

For example, a developer working on a laptop and a team member editing on a tablet can both make changes offline. When they sync, the system reconciles differences, ensuring everyone sees the latest state without complex server logic. This simplicity makes multi-device workflows smooth and predictable.

What about conflicts, failures, and data integrity?

Conflicts are inevitable in any distributed system. Threlmark handles them by treating each file as an independent unit with built-in versioning. When two edits clash, it flags the conflict for manual resolution or uses a merge strategy. For more insights, see this detailed analysis.

Crash safety is baked in through atomic writes. Every update writes to a temporary file and then renames it, so partial writes never corrupt your data. If your system crashes mid-update, the old version remains untouched.

For example, if a power outage occurs during a save, the file either stays intact or is replaced cleanly. This approach keeps your data consistent and recoverable, even in adverse conditions. According to [4], this method is essential for reliable local-first apps.

How does this architecture support schema evolution and future growth?

Schema evolution is as simple as adding new fields to your JSON files. Since unknown keys are preserved, older tools don’t break when they encounter new data. For more on managing data schemas, see this guide.

Threlmark’s tolerant normalization reads files, fills in defaults, and keeps unknown keys intact. This forward-compatible approach means your system can grow organically, without painful migrations. It’s like having a living document that adapts as your needs change.

Imagine you start tracking due dates in your tasks. Older files just ignore the new field, but newer tools will recognize and process it. This flexibility makes the system resilient to change and easy to extend.

What’s the real-world benefit of a file-based approach?

Speed, resilience, and control. When you work with files, your app responds instantly because it’s just reading from disk, not querying a remote server. It works offline without fuss, and you can back up your entire system by copying a folder. Learn more about local-first architecture at this article.

In practice, a developer might tweak a task directly in a text editor, then see the change reflected immediately in Threlmark. When offline, the app keeps functioning perfectly. Syncing later simply involves copying the folder or using a sync tool. For more about tools that facilitate this, visit WiredGuide.

For example, during a blackout, teams using Threlmark can continue managing their roadmaps without interruption. The simplicity of files makes the system both robust and flexible.

Frequently Asked Questions

What does ‘disk is the contract’ mean in simple terms?

It means your app’s data is stored directly in files on your disk, and those files define how the app works. Instead of a database, the files are the single source of truth everyone can see and modify.

How does Threlmark handle syncing data between devices?

It uses simple folder sync tools like Dropbox or Syncthing. Each task is a JSON file, so syncing just copies files, and conflicts are managed by timestamps and merge strategies.

What happens if two devices change the same task at once?

The system detects conflicts via file timestamps or version info. It then flags conflicts for manual resolution or applies smart merges, ensuring data stays consistent.

Why avoid using a database in this setup?

JSON files are more transparent, portable, and easier to back up or edit manually. This makes the system faster, offline-friendly, and simpler to migrate or extend.

Can this architecture support complex queries or indexing?

Not directly. It’s optimized for speed and simplicity. For complex searches, you can build indexes or use external tools, but the core data remains in plain files.

Conclusion

Threlmark’s approach challenges the notion that databases are the only way to build reliable, offline-capable apps. By making the disk the contract, you gain transparency, control, and simplicity.

Imagine your app as a living set of files — easy to inspect, modify, and sync. That’s the power of a true local-first system. If you want to build resilient, flexible software, start thinking about your data as files on disk. It’s a small shift with enormous potential.