Imagine managing multiple projects with a system so simple it runs entirely on plain files on your disk. No servers, no cloud, just JSON files you can open with a text editor, and everything stays in sync. That’s the core idea behind Threlmark’s local-first architecture—using the disk itself as the contract.

This approach challenges the conventional wisdom that a database is needed for consistency and collaboration. Instead, Threlmark shows that the disk can be the authoritative source, making your data portable, inspectable, and resilient. Whether you’re offline, working across devices, or collaborating with external tools, this design keeps things straightforward and reliable.

Key Takeaways

• Treat disk files—especially JSON—as the primary contract, not just storage.
• Atomic file operations are essential for safe, crash-proof updates.
• Offline-first workflows thrive when data is portable and inspectable.
• Conflict resolution simplifies when each item is a separate file with timestamps.
• This approach favors transparency and simplicity over scalability for very large datasets.

How Threlmark’s Disk-First Setup Changes Everything

Threlmark’s core move is simple: your files on disk aren’t just storage—they’re the system’s contract. Think of each JSON file as a tiny, self-contained piece of your project data. Instead of a central database, every change happens directly on these files.

For example, when you update a task card, the app writes a fresh JSON file in its dedicated folder. This file is the official record—no intermediary database needed. This means you can open, edit, or sync these files with any tool, anywhere. It’s like having a living, breathing database that’s just plain text.

And because the entire system is built around this principle, the process is transparent. No magic—just files, simple and human-readable. This transparency unlocks portability, ease of backup, and compatibility with any tool that can read or write files.

Why Local-First Matters More Than Ever

Local-first isn’t just a buzzword; it’s a game-changer. It means you can keep working even when your internet drops out or your cloud service goes down. Threlmark’s design makes this real—your JSON files are always accessible, always up-to-date locally.

Picture a team working on a shared project during a flight. No internet? No problem. They edit their JSON files on laptops, and when they reconnect, everything syncs smoothly. This is exactly what local-first promises: seamless work, no interruptions, and a natural way to handle conflicts and updates.

According to recent research, offline-capable apps increase productivity and reduce frustration. Threlmark’s approach shows that you don’t need a complex sync engine—just reliable file operations and a simple conflict policy.

Inside the JSON Layout: The On-Disk Structure Revealed

Threlmark’s on-disk layout is like a well-organized toolbox. At its core, you find a manifest (`threlmark.json`) describing the entire setup, plus a graph of dependencies (`links.json`). Each project lives in its own folder, with files for metadata, WIP limits, and lane orderings.

The real magic happens with individual cards, stored as separate files in the `items/` directory. For example, a task card might be `items/task-123.json`. These files are tiny, focused, and easy to read or edit directly.

Additional folders hold suggestions, handoffs, reports, shared items, and archives. This structure makes everything transparent—every change is a commit-able file, and you can easily back up or migrate your entire setup by copying these files.

Making File-Based State Safe: The Atomic Write Trick

Using files for critical data sounds risky, right? Threlmark sidesteps this with atomic writes—a simple but powerful technique. Every update writes to a temp file, then renames it over the original. This guarantees no partial writes or corruption even if your system crashes mid-save.

For example, updating a card involves writing `items/task-123.json.tmp` first, then renaming it. This tiny step ensures your data remains consistent. It’s like replacing a glass window with a new one—no half-finished panes.

This pattern is the backbone of safe, reliable file operations, especially when there’s no central server to enforce consistency.

How Threlmark Handles Conflicts and Syncing

Conflicts happen when multiple devices edit the same file. Threlmark addresses this with a simple principle: the latest timestamp wins, but it also preserves unknown fields and merge history. That way, no data gets lost or overwritten unexpectedly.

Sync happens by copying files—no complex protocols needed. When two devices update a card simultaneously, the system compares timestamps and merges changes, keeping the full history intact. You can learn more about local-first architectures.

For example, if your laptop and tablet both update a task, the system will automatically choose the latest change based on `updatedAt`, and keep any extra fields your tools added. This approach keeps everything consistent without a central authority.

Performance, Safety, and the Tradeoffs of File Storage

Storing everything in files isn’t just simple; it’s lightning-fast for local reads and writes. No network latency, no waiting for server responses. But, there are tradeoffs. Large projects can lead to many small files, which may impact startup times or file system performance.

Safety is built-in—atomic writes, versioning, and a straightforward conflict policy mean your data stays safe during crashes. For more insights, see how local-first systems ensure safety. Still, it requires disciplined backups and clear conflict handling, especially for teams.

Compared to a traditional database like SQLite, Threlmark’s approach trades some performance and scalability for transparency, simplicity, and offline resilience. It’s perfect for personal workflows or small teams but can stretch with very large datasets.

Real-World Use Cases: When This Architecture Shines

Threlmark’s design excels in scenarios where flexibility, portability, and offline access are key. Think solo developers managing multiple projects across devices, or teams collaborating in patchy network environments. For example, a remote team working on a shared design system can edit JSON files locally, then sync once online.

It’s also great for tool integration—external apps or AI agents can read and write files directly, making automation seamless. If you want a lightweight, transparent, multi-tool workflow, this setup is a perfect fit.

Limitations and Things to Watch Out For

This architecture isn’t perfect. It relies heavily on disciplined conflict management and backups. Large projects with thousands of files can slow down file system operations. And, if multiple devices edit without proper sync, conflicts may get complicated.

Another challenge is ensuring atomicity across networked file systems—local disks are safe, but cloud sync tools might introduce issues. Being aware of these limits helps you design better workflows.

Frequently Asked Questions

What does ‘disk is the contract’ actually mean?

It means the JSON files on disk are the definitive source of truth. All tools read and write these files directly, so the system’s state is transparent, portable, and safe from server outages.

Why use JSON files instead of a database?

JSON files are human-readable, easy to inspect, and portable. They eliminate lock-in, making backups and migrations straightforward, especially for offline or small-scale projects.

How does Threlmark sync data across devices?

It copies the JSON files directly, relying on file timestamps and conflict policies. No complicated protocols—just straightforward file sync, making offline work and manual sync simple.

What happens if two devices edit the same file simultaneously?

The system compares timestamps and merges changes, preserving extra fields and history. This keeps data consistent without requiring locks or central servers.

Is this approach suitable for team collaboration?

Yes, especially for small teams or workflows demanding offline access. But it requires discipline in conflict management and regular backups to avoid data loss.

Conclusion

Threlmark’s disk-as-contract architecture flips the script on traditional data storage. It proves that a simple, file-based system can be powerful, resilient, and perfectly suited for offline workflows. If you crave transparency, portability, and control, this model offers a compelling path forward.

Next time you pick a tool or design a system, ask yourself—could the disk itself be the contract? Sometimes, the simplest answer is the most elegant.