Imagine working on your project, offline, without any cloud. Your data is right there on your disk, structured in a way that any tool can read or write. That’s the core of Threlmark’s approach—making your disk the contract, the single source of truth that powers everything from AI assistants to multi-project roadmaps.

In this article, I’ll walk you through how this simple idea blossoms into a resilient, flexible architecture. You’ll see how it handles concurrency, external tools, and even AI automation—all without a database or a single user account. It’s a different way of thinking about data, one that puts control and portability front and center.

Key Takeaways

• Treat your disk as the primary contract—every file is a trustworthy, inspectable piece of your project.
• Use atomic writes to keep data safe during updates, avoiding partial or corrupt files.
• One file per item prevents race conditions and simplifies concurrency, even with multiple tools or AI agents.
• The system self-heals lane order and references, reducing manual errors and keeping your view accurate.
• This architecture makes backup, migration, and integration straightforward—no lock-in, no complex databases.

Why Making Your Disk the Single Source Changes Everything

Threlmark’s key move is treating the local disk not just as storage but as the contract—your definitive source of truth. This design means every file, from project configs to individual task cards, acts as a tiny, self-contained piece of your project universe.

For example, instead of a central database, each task card lives as a separate JSON file in a folder. When you update a card, you replace that file atomically—no locks, no race conditions. This simplicity makes data portable, easy to back up, and compatible with any tool that can read JSON.

It also means you’re not locked into any platform. Drop the folder into Dropbox, sync with Syncthing, or move it to another device. The data moves with you, always intact, always current—no vendor lock-in or cloud dependency.

Why does this matter? Because it shifts control from centralized servers to your own device, giving you sovereignty over your data. It also reduces complexity—no need for elaborate database management or server infrastructure. But this simplicity does come with tradeoffs: handling large projects with thousands of files can become cumbersome, and conflict resolution during sync needs careful planning. Still, for many workflows, the benefits of transparency, portability, and resilience outweigh these challenges.

How Threlmark’s File Layout Turns Data Into a Contract

Threlmark structures its data as a set of well-defined files and folders. For more on this approach, see local-first architecture. At the top, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project gets its own folder with metadata, lane order, and cards—each card as its own JSON file.

For example, a card like “Finish project proposal” exists as `items/abc123.json`. External suggestions go into `suggestions/`, while completed work moves into `archive/`. This layout isn’t just tidy; it’s a contract that any tool can read or modify without breaking compatibility.

Why does this matter? Because defining a clear file layout creates a shared understanding—any tool that follows the structure can interpret and manipulate the data without requiring proprietary APIs. This openness fosters interoperability and future-proofing, but it also means that maintaining consistency across files is crucial. If files are misnamed or misplaced, the system might misinterpret the data, leading to errors. Therefore, disciplined organization and validation are vital to preserving the integrity of this contract.

4 Big Benefits of Making Files the API

• Inspectability: Every artifact is a plain file, so you can `cat`, `diff`, or `grep` it—great for debugging or version control. This transparency allows you to understand exactly what’s stored without needing special tools.
• Portability: Move the entire project folder anywhere; no special database dump needed. This makes backups, sharing, and device migrations straightforward, giving you control over your data’s location.
• Interoperability: Any tool that reads JSON can participate—custom scripts, editors, or AI agents. This openness accelerates innovation and reduces vendor lock-in, but it also requires that external tools adhere to the file structure and handle data validation properly.
• Restartability: No in-memory state—just reload files, and everything is back in sync. This resilience means your project can recover from crashes or interruptions without complex recovery procedures.

These properties make your project data resilient, flexible, and future-proof. They encourage a mindset where data is always accessible, editable, and compatible across diverse tools, but they also demand disciplined file management to prevent inconsistencies.

Keeping Data Safe With Atomic File Writes

Imagine your computer suddenly crashes during a save. Classic risk, right? Threlmark uses atomic writes to dodge this. It writes to a temporary file, then renames it—an operation that’s atomic on most filesystems.

For example, updating a task card involves creating a temp file, then replacing the old one instantly. This guarantees no corruption, no partial writes. This pattern is crucial because it ensures data integrity even in the face of unexpected interruptions, which are common in real-world scenarios. If a write is interrupted, the original file remains intact, preventing data loss or corruption that could derail your project.

Here’s a snippet of how it works:

How One File Per Item Solves Concurrency and Keeps Things Smooth

One file per task card means no conflicts during simultaneous updates. Unlike a big JSON list, where two tools race to update the same file, here each card is independent.

This independence allows multiple tools or AI agents to work simultaneously without stepping on each other’s toes. When a tool updates a card, it replaces just that one file—no need to lock or coordinate. The broader system then reads all the individual files to rebuild the overall project view, effectively resolving conflicts on-the-fly. This approach greatly simplifies collaboration, especially in distributed environments, because each change is atomic and localized.

However, this also means that maintaining consistency across related files (like links or dependencies) requires careful handling. Automated validation or self-healing mechanisms, like the lane order correction, are essential to prevent inconsistencies from creeping in. Overall, this pattern balances concurrency with simplicity, enabling smooth multi-agent workflows.

Making the Board Self-Healing and Resilient

The lane order isn’t stored in a big list but as an ordered array of IDs inside `board.json`. When you load the board, Threlmark cross-checks against the actual item files. Missing or extra cards get automatically fixed—this is the ‘self-healing’ magic.

Imagine a card gets accidentally deleted. The next time you open the board, the system notices and removes it from the lane, keeping everything consistent without manual cleanup. This process relies on the assumption that the file system’s state is the single source of truth, and the system actively reconciles discrepancies. Such resilience is especially valuable in environments where files may be manually edited or accidental deletions occur, providing a safety net that maintains project integrity without user intervention.

This approach reduces errors and keeps your project view always accurate, but it requires that the self-healing logic is robust enough to handle edge cases and inconsistencies, which can sometimes be complex in large, dynamic projects.

External Tools and AI Agents Play Nice With Files

Since the data is just files, any tool—be it a CLI script or an AI assistant—can read and write directly. Want your AI to move a card to ‘Done’? It just updates the corresponding JSON file.

This openness makes automation straightforward. For example, an AI agent can scan the `suggestions/` folder, pick a task, and move it to `items/` with a new status. Because all operations are simple file reads and writes, there’s no need for complex API calls or permissions—just straightforward file manipulation. This simplicity promotes a highly flexible automation environment, but it also demands that external tools respect the file structure and handle potential conflicts or errors gracefully, to maintain consistency across the project.

Sync, Backup, and Migrate Without Lock-In

Backing up your project is as simple as copying a folder or syncing it with Dropbox. Moving to a new machine? Just transfer the files. Because everything is plain, interoperable JSON files, there’s no vendor lock-in.

And when combined with version control tools like Git, you get a full history of changes. Restoring or migrating becomes trivial—no complicated database exports needed. This approach empowers you to maintain control over your data lifecycle, ensuring that backups and migrations are straightforward and reliable, without relying on proprietary formats or cloud services. However, it also means that managing large projects requires disciplined organization and possibly automation to handle large volumes of files efficiently.

What Challenges Come With a Disk-as-Contract Approach?

While simple, this approach isn’t without challenges. Handling conflicts during sync can get complex, especially in multi-user setups. Conflict resolution strategies like CRDTs or careful merge rules are essential. Without these, conflicting changes might lead to data loss or inconsistencies that require manual intervention. Additionally, scalability can become an issue: large projects with thousands of files may slow down the system, making operations like loading or syncing more time-consuming. Nonetheless, for most personal and small team workflows, these tradeoffs are manageable, and the benefits of transparency, control, and resilience often outweigh the downsides. Recognizing these limitations helps you design effective workflows and choose appropriate tools for your project’s scale and complexity.

Frequently Asked Questions

How does Threlmark handle data conflicts during synchronization?

Threlmark’s architecture relies on conflict-free strategies like CRDTs and version checks. When conflicts occur, it merges changes intelligently, ensuring eventual consistency without losing data.

Can I use Threlmark with existing tools or only within its ecosystem?

Since Threlmark’s data is plain JSON files, any tool that reads and writes JSON can participate. This makes integration with custom scripts, editors, or AI agents straightforward.

What happens if I accidentally delete a file or corrupt data?

Because each file is atomic and version-controlled (if you use Git), you can recover previous states easily. The self-healing mechanisms also help keep your project consistent.

Is this approach scalable for large projects?

It works well for small to medium projects. Large-scale setups with thousands of files may face performance issues, but for personal or team workflows, it remains fast and manageable.

How does the system ensure data privacy?

All data stays on your local disk unless you choose to sync or share it. This local-first approach naturally enhances privacy and security.

Conclusion

Making your disk the contract isn’t just a technical detail—it’s a mindset shift. It turns your project data into a resilient, portable, and collaborative foundation. When you treat files as the API, you gain control, flexibility, and peace of mind.

Next time you set up a project, remember: simplicity and transparency often beat complexity. Your disk is more than storage—it’s the contract that keeps everything honest, connected, and ready for whatever comes next.