Imagine working on your project, unplugged, yet everything still flows smoothly. No server hiccups, no waiting for cloud sync. That’s what Threlmark’s local-first architecture promises. The secret? The disk is the contract—your entire app’s state lives in simple, human-readable JSON files. This design flips traditional databases on their head, making data accessible, portable, and resilient.

In this deep dive, you’ll see how a file-based, decentralized approach empowers your workflow, simplifies multi-device sync, and even allows AI agents to work autonomously. It’s a different way of thinking about app architecture—more straightforward, more reliable, and built for the offline age.

Key Takeaways

• Making disk the contract simplifies data management, making everything inspectable, portable, and reliable.
• JSON files enable offline-first workflows, allowing seamless work without internet and easy debugging.
• One file per item reduces race conditions and makes concurrency safer, especially for multi-device setups.
• Sync is about reconciling changes through conflict resolution strategies—eventual consistency works well.
• Schema evolution is manageable because unknown keys are preserved, ensuring long-term flexibility.

Why Making Disk the Contract Changes Everything

When the disk becomes the system’s contract, every file is an authoritative record. That means your app reads and writes directly to files—no hidden database layers or complex APIs. Threlmark’s design treats the file system itself as the database, which is surprisingly simple and powerful.

Picture this: Your project’s roadmap is a folder full of JSON files. Each task, each card, is a small file you can open, edit, or review with a simple text editor. No need to connect to a server or run a fancy database. This approach makes data transparent and easily portable—just copy the folder, and you’ve backed up your entire project.

How JSON Files Power Offline-First, No Cloud Needed

Threlmark uses plain JSON files stored locally. This makes the system inherently offline-capable. You can add, change, or review tasks anytime—no internet required. When you reconnect, the app can sync changes with other devices or tools.

For example, if your laptop crashes, your project isn’t lost—just restore the folder. If you’re on a plane, your work continues. Once back online, syncs reconcile changes across devices smoothly, because each device works with the same files.

According to the local-first movement, this pattern reduces errors, speeds up workflows, and keeps you in control of your data.

The File Layout That Keeps Everything Clear and Safe

Threlmark’s folder structure is a blueprint for clarity. At the root, you find a manifest (`threlmark.json`) and dependency graph (`links.json`). Each project has its folder, with files for metadata (`project.json`), order (`board.json`), and individual cards (`items/.json`).

When you update a card, the system writes directly to its own file—atomically—avoiding corruption. If you move a card, just edit the pointer. This modular setup makes debugging, backup, and migration straightforward.

It’s like having a well-organized filing cabinet—every piece is accessible, and nothing gets lost or overwritten.

Why One File per Item Beats Bulk Lists

Instead of a giant JSON array for the whole roadmap, Threlmark stores each task in its own file. This means updates are atomic—no race conditions or clobbered data. External tools can modify individual cards without touching everything else.

For example, a task might be a short JSON like `{ “id”: “task1”, “title”: “Write report”, “status”: “in progress” }`. Updating this file is quick, safe, and easy to review. Meanwhile, the `board.json` file simply lists IDs in order, and is self-healing — reconciling itself whenever read.

Sync, Conflict, and Collaboration — How It All Works

In Threlmark, syncing is about reconciling JSON files across devices. Changes are committed locally, then pushed to other devices via file sync tools or manual copying. Conflicts happen if two devices edit the same file; your app can detect and resolve these by timestamp or manual review.

This model favors eventual consistency. Imagine editing on your laptop, then later on your tablet—the app detects changes, merges where possible, and flags conflicts in local-first architectures. This way, your data remains reliable, even in chaotic multi-device setups.

Research shows that conflict resolution strategies—like last-write-wins or manual merge—are essential for smooth collaboration in local-first apps [4].

Tradeoffs of Going File-First Instead of Database

Choosing plain files over a database simplifies many things—no server, no schema migrations, and transparent data. But it also shifts complexity into sync and conflict handling. For large projects, managing thousands of files can slow down access and complicate searches.

For example, a project with hundreds of cards might need indexing or caching. Yet, for small to medium projects, the simplicity wins. Plus, the human-readable JSON makes debugging a breeze.

It’s a tradeoff: simpler in some ways, more hands-on in others. But for offline, multi-device workflows, the benefits often outweigh the downsides.

Handling Schema Changes and Data Evolution

When your data schema evolves, older files may not match new expectations. Threlmark’s approach preserves unknown keys, so old files remain readable and updatable. You can add new fields without breaking existing tools.

For instance, if you add a new `priority` field to tasks, old files just ignore it until they’re updated. This forward compatibility is a big plus for long-term projects.

Regular migrations or scripts can update old files en masse, ensuring your data stays current without losing history.

Debugging, Backup, and Data Portability Made Easy

Because everything is plain JSON files, debugging becomes as simple as opening a file. You can `cat` it, run `diff`, or review change history with your favorite tools. Backups are just copying folders—no special tools needed.

Want to migrate? Just copy the entire directory. Need to inspect a specific task? Open its file. This transparency makes data management accessible to everyone.

Performance and Scalability — When File-First Can Slow Down

Handling hundreds or thousands of files can slow down the system if not managed properly. Indexing and caching help, but beyond a certain scale, a pure file-based approach may need optimization.

For example, large projects with thousands of tasks might benefit from additional indexing layers or hybrid solutions. But for most personal or small-team projects, the simplicity remains a major advantage.

When to Use Threlmark’s Approach

If your project needs offline access, easy debugging, and multi-device sync—without complex infrastructure—Threlmark’s file-based design is a perfect fit. It’s especially good for solo developers, small teams, or knowledge workers who value transparency and control.

For collaboration-heavy apps with real-time edits or hundreds of users, a traditional database might still be better. But for personal productivity, prototyping, or niche apps, this approach shines.

Frequently Asked Questions

What does “disk is the contract” actually mean?

It means that the files stored on disk are the definitive source of truth for the app’s data. All components read from and write to these files directly, making data transparent and consistent.

Why choose JSON files instead of a database?

JSON files are human-readable, easy to inspect, and portable. They simplify debugging, backup, and migration, especially in offline or low-complexity scenarios.

How does the app work offline?

Because all data lives in local JSON files, you can read, modify, and save your project without an internet connection. Sync happens later to reconcile changes across devices.

How are conflicts handled when multiple devices edit the same data?

Conflicts are detected based on timestamps or change detection. The system can automatically merge changes or prompt manual resolution, ensuring data integrity.

What are the downsides of a file-based architecture?

Handling many files can slow down performance at scale, and managing large projects may require additional indexing. But for small and medium projects, simplicity often outweighs these concerns.

Conclusion

Threlmark’s disk-as-contract architecture proves that simple, file-based storage can handle complex, multi-device workflows with ease. It’s a reminder that sometimes, going back to basics—plain files and thoughtful structure—creates the most robust and transparent systems.

Next time you build or choose a tool, ask: can I make disk the contract? The answer might just transform your app’s reliability, debugging, and offline capabilities.