Imagine managing your entire project, not through a web app, but directly on your disk—where every file is a living, breathing part of your workflow. That’s the core idea behind Threlmark’s local-first architecture. It’s a surprisingly simple twist: your data lives in plain JSON files, and these files are the system’s contract, not a database or cloud service.

This approach might sound risky or old-fashioned. But it’s also incredibly flexible, reliable, and open. It changes how you think about data, collaboration, and automation. Today, I’ll walk you through how this disk-as-contract design works, why it’s so powerful, and what it means for your projects.

Key Takeaways

• Treat your disk as the ultimate record—use files as the API to simplify data management.
• Plain JSON files enable human-readable, portable, and lock-free project data.
• Offline work becomes instant and reliable when data lives locally, with sync layered on top.
• Atomic file operations prevent corruption and ensure data safety, even during crashes.
• Scaling to multi-device collaboration requires a clean sync layer and conflict resolution, built around the file system.

Why Using Your Disk as the Single Source of Truth Changes Everything

In most apps, data lives in a database or cloud service. But Threlmark flips that script. The files on your disk are the real record, the source of truth. This means you can open the files in any editor, see exactly what’s stored, and trust that what’s on disk is always right.

For example, if you’re working on a project and want to see the latest task list, just open the JSON file. No waiting for server responses. No worries about sync conflicts—because you’re always working directly with the real data, right there on your machine.

This approach simplifies debugging, backups, and migration. A quick copy of your project folder is all you need to clone your entire workflow. And it’s inherently open: any tool or script can participate just by reading or writing files. Learn more about local-first architecture.

How Threlmark Uses Plain JSON Files Instead of a Database

Threlmark’s setup is refreshingly simple: each project’s data is stored in a directory full of JSON files. Every task, card, or project detail gets its own file—like item123.json. This prevents conflicts, because updating one file is atomic and independent.

For example, changing a task’s status involves rewriting just that file. No need for complex transactions or lock management. The files sit in a folder like ~/.threlmark/items/, easily accessible and human-readable.

Compared to databases, JSON files are transparent and portable. You can open them in your editor, diff them with Git, or migrate everything by copying a folder. No vendor lock-in, no proprietary format.

Making Offline Work Seamless and Speedy

When your data lives on disk, working offline feels instant. You edit a JSON file, and your changes are immediate. No network delay, no server downtime. That’s a game-changer for resilience and speed. Read more about local-first architecture.

For example, while traveling or in a spotty Wi-Fi zone, you can add tasks, move cards, or update priorities. As soon as you’re back online, you can sync your changes—if needed—without losing anything.

This setup aligns perfectly with the offline-first principle: your app remains usable, fast, and reliable, no matter what the network does.

How Sync and Conflict Resolution Work in a File-Based World

Syncing isn’t baked into the files themselves but layered on top. Threlmark uses a separate sync layer that compares files, merges changes, and resolves conflicts. When two devices edit the same card, the system compares the JSON files and intelligently merges updates. Find out more about local-first sync.

For example, if one device updates a task’s priority while another adds a comment, the sync process combines these changes smoothly. Conflicts are handled by favoring the latest change or prompting for manual resolution, depending on the setup.

This approach avoids complex lock management or server-side conflict resolution. Instead, it relies on straightforward file diffing and merging, making conflicts transparent and manageable.

Unlocking Collaboration Without Lock-In or Cloud Dependence

One of the coolest parts? You can share your entire project folder—just like sharing a folder in Dropbox or Git. External tools, scripts, or even manual edits can participate without special permissions. For more insights, see local-first collaboration.

For example, a teammate could edit a JSON file directly, or a script could suggest a new task by dropping a file into the suggestions folder. Threlmark then recognizes and incorporates these changes seamlessly.

This openness enables multi-device, multi-user workflows without tying everything to a central server or vendor lock-in. You’re in control of your data, all the time.

The Role of the Agent in Orchestrating the Workflow

An agent is a background process that helps automate tasks—like moving cards, syncing, or updating statuses—based on rules or AI suggestions. In Threlmark, the agent watches folders like handoffs/ and reports/, acting as a smart coordinator. Learn more about workflow orchestration.

For example, an AI agent might scan suggestions, pick the most important task, and move it to “Done” without human intervention. Or it might resolve conflicts by comparing file timestamps and merging changes.

This setup makes automation transparent and flexible. The agent relies on the same files you work with, maintaining the system’s integrity and simplicity.

The Big Tradeoffs: Simplicity vs. Scale

Using files instead of a database isn’t just elegant; it has limits. For small to medium projects, it’s fast, simple, and transparent. But as data grows, managing thousands of JSON files can become a challenge.

For example, a project with hundreds of active tasks might slow down file lookups or complicate syncs. You might need to introduce indexing or a lightweight database at some point.

However, for many teams, the tradeoff favors simplicity and control. It’s a matter of understanding your scale and needs.

Keeping Your Files Safe and Your Data Consistent

Safe file operations are critical. Threlmark uses atomic writes: each update writes to a temp file, then renames it. This way, crashes or interruptions don’t corrupt your data.

For example, if your laptop loses power mid-save, the original JSON file remains intact. You can confidently backup folders or use version control to track changes.

Plus, JSON’s human-readable format makes troubleshooting easier—just open a file and see what’s inside.

From Single Device to Multi-Device Collaboration — What Changes?

Scaling from one device to many means adding a sync layer and conflict management. The core principle remains: the files are the source of truth. But now, you need tools to keep everything aligned.

For example, syncing across a laptop and a tablet involves comparing JSON files, merging changes, and resolving conflicts. Threlmark’s design makes this straightforward—no complex server needed.

This model empowers teams to work seamlessly across devices, with the same straightforward file system supporting both solo and collaborative work.

Tradeoffs vs. Traditional Server-Client Architectures

Traditional apps rely on a centralized server and databases. That’s powerful but adds complexity, lock-in, and potential points of failure. Threlmark’s approach is lean: files, sync, and automation.

For example, working offline is effortless—just edit the files. But scaling to hundreds of users or real-time collaboration might require more infrastructure.

Both architectures have their place. File-based systems excel in simplicity, safety, and control, especially for personal projects or small teams.

Frequently Asked Questions

What does ‘disk is the contract’ really mean?

It means that your project’s data lives in files on your disk, which serve as the single source of truth. No database, no cloud dependency—just plain files you can edit, diff, and back up.

Why use JSON files instead of a database?

JSON files are simple, human-readable, portable, and easy to modify with any editor. They avoid vendor lock-in and make debugging and migration straightforward.

How does syncing work if I’m offline?

When offline, all changes are made locally. Once back online, the sync layer compares files, merges updates, and resolves conflicts. Everything stays consistent without needing a constant connection.

What happens if two devices edit the same task?

The sync layer compares JSON files and merges changes based on timestamps or rules. Conflicts are either automatically resolved or flagged for manual review, keeping your data safe.

Is this approach safe? What if files get corrupted?

Yes, if you follow atomic write patterns. Writing to temp files and renaming prevents corruption. Regular backups and version control further protect your data from loss or damage.

Conclusion

Threlmark’s disk-first architecture turns the traditional app model upside down. By making the disk the contract, it creates a system that’s simple, resilient, and open—perfect for solo creators or small teams who want control and flexibility.

Imagine a future where your project data is always with you, perfectly synced, ready to be inspected, modified, and automated—without locking you into a cloud or database. That’s the promise of treating disk as the contract.