Imagine a tool where your data isn’t locked behind a server or cloud, like the assistive technology solutions that enhance accessibility. Instead, it lives right on your disk, accessible and editable with a simple text editor. That’s the core idea behind Threlmark’s local-first architecture. It’s a radical shift from traditional apps that rely on centralized databases. Here, your entire project roadmap, tasks, and AI interactions are stored as plain JSON files. No vendor lock-in, no server dependencies, just pure files sitting on your machine. This approach isn’t just about storage; it’s about creating a system that’s more resilient, transparent, and flexible. Whether you’re offline, collaborating across devices, or automating your workflow, Threlmark’s design makes it all possible with a simple, elegant principle: disk is the contract.

Key Takeaways

• Treat your data as files on disk — it’s portable, transparent, and safe from vendor lock-in.
• Use atomic write patterns to prevent corruption, especially when working with multiple tools or collaborators.
• Store each item in its own file to simplify concurrency and improve robustness.
• Design your system to be stateless — restartability ensures resilience and ease of automation.
• Leverage open files for seamless multi-device workflows and AI automation.

Why Using Disk as the Single Source of Truth Changes Everything

In Threlmark, the on-disk layout isn’t just a storage choice — it’s the core of the system’s reliability and flexibility. All data lives in plain JSON files, which any tool or script can read or modify. This makes the data inherently portable, easy to back up, and compatible with other tools.

For example, if you want to migrate your roadmap to another app, just copy the folder. No databases to export, no vendor lock-in. This simple design also means that if your system crashes or your app updates, your data remains safe and intact.

According to the Threlmark project on GitHub, this approach ensures every artifact — from project metadata to individual cards — is inspectable and versionable. You can see exactly what’s happening by just opening a file or running a diff. It’s a transparent window into your work, making debugging and collaboration smoother than ever.

How Threlmark’s File Layout Acts Like a Contract You Can Trust

Threlmark’s on-disk layout isn’t a random collection of files — it’s a formal contract. At the root, you’ll find a manifest (threlmark.json) and a dependency graph (links.json). Each project has its own folder with metadata, lane setup, and one file per task or card. This structure makes it easy to understand, modify, or extend the system without surprises.

For example, if you want to add a new project or move a card, just create or edit the relevant JSON file. No need for complex migrations or database schemas. It’s a straightforward, predictable system that anyone can pick up and trust.

As the Threlmark documentation notes, this layout promotes interoperability. Other tools can join in by simply reading and writing these files, creating a vibrant ecosystem that’s open and flexible.

Making File-Based State Safe and Reliable — No More Corruption Fears

Handling files might sound risky, but Threlmark takes careful steps to keep data safe, much like the principles discussed in this article. Every write goes through an atomic process: first writing to a temporary file, then renaming it over the original. This simple trick ensures that even if your system crashes mid-write, your data remains consistent, similar to how outdoor safety gadgets ensure reliability in the wilderness.

For instance, when updating a card, the app writes the new JSON to a temporary file like card123.json.tmp. Once complete, it renames this file to replace the old one. Because renaming is atomic on most filesystems, you avoid half-written or corrupted data.

Additionally, Threlmark uses a read-merge-write cycle, which preserves crucial info like IDs and timestamps, and tolerates unknown or missing fields. This makes the system forward-compatible and robust against schema changes, according to the system’s design principles.

How Single-File Per Item Boosts Concurrency and Simplicity

Instead of a giant JSON array for all tasks, Threlmark stores each card as its own file inside an items/ folder. This tiny change makes a big difference. When you update one card, you only write that single file, avoiding complex locks or race conditions.

For example, if you’re collaborating with a teammate editing different cards, each can save independently without clobbering the other. The system’s self-healing board.json ensures the visual flow always matches the actual cards present. If a card gets deleted or moved, the board automatically updates itself on read.

This approach simplifies concurrency and makes the system more resilient to simultaneous edits — no need for a central database or locking mechanisms.

Why Open, Portable Files Make Your Workflow Smarter

Open files are your best ally. With Threlmark, every artifact is a plain JSON file you can open in any editor, run diffs on, or back up with a simple copy. This openness means your data is never trapped in a proprietary format.

For example, if you decide to switch to a different tool or just want to peek inside your roadmap, you can. No exporting, no complex integrations — just open the files and see what’s happening.

This portability also means you can sync your data across devices using Dropbox, Syncthing, or even just git. It’s a lightweight, flexible way to keep your work consistent everywhere.

Making the System Restartable — No State, Just Files

Threlmark’s design is stateless. It doesn’t rely on in-memory databases or server sessions, similar to the approach described on home entertainment and tech guides. Instead, it reads from disk every time, so even if you restart your computer or the app crashes, your data is intact and ready to go.

For instance, when you launch Threlmark, it rebuilds the current view by reading the JSON files. No lost data, no complicated recovery steps. This makes the system incredibly resilient and easy to maintain.

Plus, this approach makes automation and external tools easier to integrate, since they can just read and write files at will. No special APIs required.

How Threlmark Enables Seamless Offline and Multi-Device Work

Because all data lives on disk, you can work offline without breaking a sweat. Just open your files, make changes, and save. When you reconnect, sync tools automatically update other devices.

For example, if you’re traveling and working on your laptop, your roadmap updates instantly when you reconnect to Dropbox or Syncthing. No need to worry about server availability or conflicts — the system is designed for offline resilience.

This model supports multi-device workflows effortlessly, making Threlmark ideal for teams that split their work across laptops, tablets, or even shared folders.

How Automation and AI Agents Work with Files — Closing the Loop

Threlmark’s file-based design makes it easy for AI agents and automation scripts to participate. They simply read and write the JSON files, updating cards or moving tasks to Done.

For example, an AI agent might scan the reports/ folder, find a completed task, and move its card to the done/ folder. Because the entire system is just files, automation becomes a natural part of the workflow.

This setup allows the system to close the loop: AI can review, update, and even trigger new actions without needing a complex API or database, just plain files.

Frequently Asked Questions

What does it mean that ‘disk is the contract’ in Threlmark?

It means all data lives in plain JSON files, which serve as the single source of truth. This makes the system transparent, portable, and easy to modify without relying on databases or cloud services.

How does Threlmark handle multiple devices or offline work?

Because all data is stored on disk, you can work offline and sync changes later using tools like Dropbox or Syncthing. The system is designed for resilience and multi-device collaboration without central servers.

Is this approach safe from data corruption?

Yes. Threlmark uses atomic write techniques, writing to a temporary file and renaming it, which prevents corruption even if the system crashes during a write.

Can external tools or AI agents participate easily?

Absolutely. Since everything is plain JSON files, external scripts and AI agents can read and modify data directly, enabling automation and closing the loop naturally.

What are the main benefits of this file-based architecture?

It’s open, portable, restartable, and easy to extend. You gain transparency, resilience, and flexibility, making it ideal for modern, offline-capable workflows.

Conclusion

Threlmark’s core insight is simple but powerful: the disk isn’t just storage. It’s the contract that makes the entire system honest, flexible, and resilient. When you treat files as the single source of truth, you build a tool that’s easy to extend, debug, and trust. In a world of complex databases and cloud lock-in, this approach stands out as refreshingly straightforward and remarkably effective. Your next project could benefit from this clarity — just start with the files on your disk.