Imagine working on your project, making changes, and knowing your data is safe right there on your disk. No cloud, no server, no middleman. That’s the core idea behind Threlmark’s local-first architecture — the disk isn’t just storage; it’s the contract that defines everything.

This approach turns traditional app design on its head. Instead of relying on a central database or an online server, Threlmark treats files on your device as the single source of truth. It’s a game-changer for offline work, multi-device sync, and building simpler, more transparent apps. In this deep dive, I’ll walk you through how this architecture works, why it’s so powerful, and what it means for the future of app design. Learn more about local-first architecture.

Key Takeaways

• Treat the filesystem as your app’s API — it simplifies architecture and improves resilience.
• Use JSON files for their readability, portability, and compatibility with atomic write techniques.
• One file per item prevents race conditions and makes concurrent editing straightforward.
• A layered directory structure enforces discipline and makes data easy to back up or migrate.
• Atomic writes and tolerant merging ensure data safety and forward compatibility.

Why Making Disk the Contract Turns Apps Into Super-Resilient Machines

When your app’s data lives directly on your disk in JSON files, it becomes inherently more resilient. If your internet drops, your work doesn’t stop. You just keep editing, reading, and saving — because the data is right there, on your device.

Take a real-world example: a designer working on ideas across multiple devices. With Threlmark, her sketches, notes, and task lists stay available offline, no matter where she opens her laptop or tablet. When she reconnects, syncing is just a matter of copying files — no complicated conflict resolution needed.

This setup also simplifies debugging and extension. You can open a file, see exactly what’s stored, and even edit it manually if needed. Plus, it’s compatible with any language or tool that can read/write files, making integrations a breeze. The core idea? The filesystem itself becomes the API, a trusted source of truth that’s simple, transparent, and robust.

How Threlmark Stores Data — JSON Files That Speak Your Language

At the heart of Threlmark’s design is JSON — human-readable, flexible, and easy to work with. Every project, card, or task is a JSON file stored in a dedicated folder. For instance, each roadmap item lives in items/ as its own file — think of it like a separate note on your desk, always accessible. Explore more about data formats in app design.

Why JSON? Because it’s simple to inspect, diff, and merge. If you want to see what a task looks like, just open the file in your editor. Want to update its priority? Edit the JSON directly. This transparency makes data manipulation straightforward and safe, especially with atomic write techniques that prevent corruption during crashes.

Imagine working on a project, and manually editing a task’s JSON to prioritize it. When you save, the system atomically replaces the file, avoiding race conditions. This simplicity keeps the data consistent, even if multiple tools or devices modify files at once.

Why One File Per Item Beats Big JSON Files for Concurrency

Picture this: instead of a giant roadmap.json that holds all your tasks, Threlmark keeps each item as its own file. This tiny shift—one file per task—eliminates race conditions and makes updates lightning-fast.

Suppose two devices are updating different tasks simultaneously. With a big JSON file, they’d risk overwriting each other. But with individual files, each change is atomic. The system only needs to replace one file, not juggle a huge list.

And because the files can be read and written independently, multiple tools or users can work at once without conflicts. The system’s self-healing properties, like reconciling the lane order from board.json against existing items, keep everything consistent automatically.

How the Layered Filesystem Structure Keeps Everything Organized

Threlmark’s directory layout isn’t random; it’s a precise contract. At the root, you find threlmark.json and links.json, defining the core project metadata and dependencies. Each project has its folder with project.json, board.json, and then the key items/ folder holding individual task files. See how directory structures enforce data integrity.

External suggestions go into suggestions/, and completed or archived projects move to archive/ — all readable, all portable. Shared tasks are stored under shared/items/. This structure keeps everything predictable, making it easy to back up, sync, or manually edit.

Imagine a team sharing a folder on Dropbox. Anyone can peek into items/ and see the latest task states without needing a special database or server. It’s a simple, transparent contract that everyone can follow.

Keeping Data Safe with Atomic Writes and Tolerant Merging

Atomic writes are the backbone of safe file updates. Threlmark writes to a temporary file first, then renames it over the original. This guarantees that a crash or power failure doesn’t corrupt your data. Discover more about data safety techniques.

Imagine editing a task on your laptop. The system saves your changes as task.json.tmp, then instantly swaps it in. The original remains untouched until the new file is ready, so no half-written files are ever seen.

Additionally, the system reads files with a tolerant merge: missing fields get defaults, unknown keys stay untouched, and scores are clamped. This forward compatibility means you can add new features or tools without breaking existing ones — the files just evolve naturally.

Sync and Conflict Handling — Making Multi-Device Work Seamless

Syncing in Threlmark isn’t push or pull alone; it’s a continuous dance. Changes made locally are saved as files, then synchronized across devices via file sharing or cloud storage. Conflicts are rare because each file is atomic, and the system can reconcile differences by re-reading files and applying simple rules. Learn about seamless multi-device sync.

For example, if you edit a task on your phone and your laptop simultaneously, the last write wins at the file level. But more sophisticated tools can compare timestamps or merge changes intelligently. The key is that the architecture doesn’t rely on a central server — just files that any device can access and update.

This setup means your data stays consistent and accessible, even if some devices are offline temporarily. Once reconnected, the sync process quietly harmonizes all the changes without user intervention.

Developer Simplicity: Less Code, Fewer Bugs, More Power

When your app treats the disk as its main contract, your code gets simpler. No need for complex API layers, database drivers, or network error handling. Just read, write, and trust the filesystem.

For instance, updating a task involves just editing a JSON file and saving it atomically. No worries about partial updates or race conditions — the system handles that for you.

This simplicity means fewer bugs, easier debugging, and faster feature development. Plus, developers can peek directly into data files, making manual fixes or experiments straightforward.

Frequently Asked Questions

What does ‘disk is the contract’ mean?

It means the application’s core data is stored directly in files on your device, and these files define the system’s state. The app reads and writes these files as the single source of truth, making data transparent, portable, and easy to manage.

How is Threlmark’s architecture different from traditional server-based apps?

Unlike apps that rely on centralized databases or cloud servers, Threlmark keeps data locally on your disk. Syncing happens later, and the system’s logic depends on files rather than a remote source, offering better offline resilience and simpler data handling.

Why use JSON files instead of a database?

JSON files are human-readable, easy to diff, and portable. They allow direct manual editing, straightforward merging, and atomic updates, which reduce complexity and increase transparency compared to traditional database systems.

How does syncing work in a local-first system?

Syncing involves copying updated JSON files across devices via cloud storage or file sharing. Since each change is an atomic file update, conflicts are minimized, and the system can reconcile differences automatically or manually.

What happens when I’m offline?

You can continue working without interruption because your data is stored locally. Changes are saved directly to disk, and syncing occurs automatically once you reconnect to the network.

Conclusion

The future of building resilient, offline-capable apps might just be writing to your disk first. Threlmark shows that by making the disk the contract, you can create systems that are simpler, more reliable, and more open to collaboration.

Imagine your next app not relying on servers or complex databases but instead trusting the humble file system to hold everything — that’s the power of a local-first, disk-as-the-API approach. It’s a quiet revolution that puts you back in control.