Imagine your app could work perfectly offline, instantly reflect changes, and sync seamlessly without a complicated backend. That’s the promise of Threlmark’s local-first, disk-based architecture. It’s a bold shift from traditional cloud-centric models, putting the disk front and center as the single source of truth.

In this deep dive, you’ll see how storing every piece of data as a simple JSON file on your disk changes everything—how it makes your app faster, safer, and more open. No database lock-in, no server dependencies, just a straightforward, elegant approach to managing complex workflows across devices. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

Key Takeaways

• Storing each item as a JSON file on disk creates a simple, portable, and reliable source of truth.
• Atomic file writes and tolerant merging prevent corruption and support smooth schema evolution.
• The architecture enables offline work, instant UI updates, and effortless multi-device sync.
• By making the disk the contract, you eliminate the complexity of server dependencies and lock-in.
• This approach is ideal for apps prioritizing speed, collaboration, and data control.

What Does ‘Disk Is the Contract’ Actually Mean?

“Disk is the contract” means your app’s data lives directly on your disk in a structured, predictable format—specifically JSON files. This setup makes the disk the ultimate source of truth, not a database or cloud service. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

For example, when you update a task in Threlmark, it writes a JSON file in a specific folder. Every app, script, or AI tool that reads that folder sees the current state, no matter if you’re offline or online.

This approach simplifies the architecture, because if the files are consistent and correct, the app’s behavior is predictable. It also means you can back up, migrate, or sync your data easily by copying files.

How Threlmark Uses JSON Files to Keep Everything in Sync

Threlmark’s architecture revolves around one file per item, stored in the directory `items/`. Each JSON file represents a task, idea, or card, with all its details.

When you move a card, add a comment, or mark it done, the app updates just that one file. It uses atomic writes—saving to a temporary file then renaming—to prevent corruption.

Lane orderings and other metadata live in separate files, like `board.json`. These self-healing structures reconcile differences on each read, so the system stays consistent even if files get out of sync or are edited outside the app.

For example, if you manually edit a card’s JSON, the app recognizes the change next time it scans, updating the interface without losing data.

Why Going Local-First Beats Cloud-Only for Speed and Reliability

Threlmark’s local-first approach means your data is always accessible, even if your internet drops. The app updates instantly from local files, not waiting for server responses.

Imagine editing a task on a plane or in a remote cabin—your changes save immediately, no lag, no error messages. When you’re back online, it syncs silently in the background.

This model reduces network dependency, cuts down error states, and enhances performance because the app doesn’t chase server responses for every tiny update.

According to recent discussions on offline-first apps, this method boosts user experience by making work feel instant—without sacrificing eventual consistency.

How the Architecture Supports Collaboration and Multi-Device Work

With each device reading and writing JSON files locally, Threlmark supports multi-device workflows naturally. When you sync, it’s just copying files—no complex conflict resolution required.

Suppose you work on your laptop in the morning and your tablet in the evening. Changes made on one device appear on the other after sync, because both read the same files. Read more about local-first architecture

In case of conflicting edits—say, two devices change the same task offline—Threlmark can apply simple conflict resolution strategies, like last-write-wins or merge prompts, since all data is just files.

This flexibility enables real-time collaboration and asynchronous updates, similar to how Dropbox or Google Drive sync files, but with a focus on structured JSON data.

Comparison Table: Local-First JSON-on-Disk vs. Traditional Cloud Apps

Feature	Threlmark (Local-First JSON)
Data Storage	JSON files on disk, per item
Sync Method	File copying and conflict resolution
Offline Access	Always available; no internet needed
Setup Complexity	Simple, no backend server
Data Portability	High; just copy files
Performance	Immediate updates from local disk
Conflict Handling	Merge or last-write-wins, manual fixes

Handling Schema Changes Without Breaking Everything

Schema changes are inevitable. Threlmark handles this gracefully by preserving unknown fields during reads and writes. This means older tools can still read newer files, and vice versa.

For example, if you add a new property to a task structure, older versions of the app will ignore it but won’t break. When you upgrade, the new property is read and preserved, ensuring smooth evolution.

This forward-compatibility is crucial for long-term projects, where data schemas evolve faster than the apps themselves.

Security, Data Integrity, and Recovery in a Disk-Backed System

Data integrity relies on atomic writes and careful file management. If a disk gets corrupted, simple file backups or version control restore the data.

For example, you can back up your `~/.threlmark` folder, restore from a previous state, or even use checksum verification during reads. These steps keep your data safe without complex recovery processes.

Because all data is plain JSON files, you can audit, edit, or recover data manually if needed—no proprietary database lock-in or recovery tools required.

Who Benefits Most From This Architecture?

This design shines in apps where speed, offline work, and collaboration matter. Think task managers, note apps, design tools, or any software supporting multi-device workflows.

For example, a small team working on a shared project can edit their tasks offline, then sync seamlessly. The app remains fast and reliable, even without a server connection.

It’s especially appealing to developers and power users who want control, portability, and simplicity in their tools.

Frequently Asked Questions

What does ‘disk is the contract’ really mean?

It means your data’s structure and state are stored directly on your disk as JSON files. These files define how your app behaves, making it simple, transparent, and portable.

How is this different from a traditional cloud app?

Unlike cloud apps that rely on a central server, a disk-based approach keeps data local, updates instantly, and syncs by copying files. This makes the app faster and more resilient offline.

How do conflicts get resolved when multiple devices edit offline?

Threlmark uses simple conflict resolution strategies like last-write-wins or manual merges, since all data is just files. This keeps things straightforward and predictable.

Is this architecture suitable for large-scale enterprise apps?

It’s best suited for small to medium apps where offline speed, data control, and simplicity matter most. Large enterprises might need additional layers for compliance and scale, but the core ideas still apply.

How do I handle schema changes without breaking my app?

Threlmark preserves unknown fields during reads and writes, so schema updates won’t break existing data or older tools. It’s a flexible, future-proof design.

Conclusion

Threlmark’s disk-as-the-contract approach flips traditional app architecture on its head. It proves that simplicity, transparency, and local control can power powerful, resilient tools.

Next time you build or choose a tool, ask yourself: what if the disk was the source of truth? The results might just surprise you—and make your system more flexible, reliable, and ready for the future.