What if your data’s most trustworthy home isn’t in the cloud, but right on your own disk? Threlmark proves it’s possible—and powerful. It flips the script, making your local files the single source of truth for your entire project ecosystem.

This design isn’t just about storage. It’s about building a resilient, privacy-focused system where external tools and AI agents can seamlessly participate, all without a central database or cloud dependency. You’ll learn how this simple yet radical choice shapes every aspect of Threlmark’s architecture—and why it might change how you think about data forever.

Key Takeaways

• Storing data on disk as the single source of truth simplifies backup, sync, and migration—no database lock-in needed.
• Using one file per item makes concurrent updates safe and conflict-free, especially for offline and multi-tool workflows.
• The directory structure acts as a clear, inspectable contract, enabling seamless interoperability and future growth.
• Atomic file writes and tolerant merge patterns keep data safe and growth-friendly over time.
• A self-healing project board maintains consistency, reducing manual cleanup and errors.

How ‘Disk Is the Contract’ Changes Everything for Your Data

At its core, “disk is the contract” means your local files are the authoritative source of truth. No servers, no cloud, just files on your disk. Think of it like a shared notebook—every app, tool, or AI agent reads and writes to the same pages, trusting that the disk holds the real story.

For example, instead of a database that tracks your project cards, Threlmark stores each card as a separate JSON file. When you update a card, it’s a simple file overwrite—atomic, safe, and straightforward. This setup makes it easy to back up, sync, or even manually edit your data without breaking anything.

Why does this matter? Because it shifts the control and trust from complex, opaque systems to transparent, inspectable files. This transparency allows you to verify your data’s integrity at any moment—if something goes wrong, you can pinpoint the exact file and change it directly. It also simplifies data recovery and migration, reducing dependency on proprietary tools or cloud services that might obscure or lock your data in unreadable formats.

However, this approach demands discipline: you need to ensure files are consistently updated and carefully managed to prevent corruption. The tradeoff is that you gain full control, visibility, and portability—powerful advantages for privacy-conscious or offline workflows.

Why a Single File per Item Makes Concurrency and Safety a Breeze

Threlmark’s use of one file per item might seem minor, but it’s a game-changer. When each card lives in its own JSON file, external tools can update or even delete individual cards without risking conflicts or corrupting the entire project.

This design choice reduces complexity: instead of locking the entire database or managing complex merge conflicts, each file acts as an independent unit. This independence means that concurrent modifications—say, from a script, an AI, or a collaborator—are less likely to cause errors. If you want to learn more about local-first architecture, this is a great example.

Why is this important? Because it enables true offline and multi-tool workflows. You can work asynchronously, perform manual edits, or automate updates without worrying about overwriting or losing data. When conflicts do occur—such as two processes editing the same file—the system can detect discrepancies and resolve them through simple merge strategies, often favoring the latest change or prompting for manual review. This approach ensures safety without sacrificing flexibility or control.

In essence, the single-file-per-item model promotes resilience, scalability, and ease of recovery—especially critical in environments where internet access is unreliable or when working with multiple tools that don’t share a common database.

How The Directory Structure Acts as a Contract — Not Just a Folder List

The way Threlmark organizes its files isn’t random. It’s a carefully designed contract. The root contains a manifest (`threlmark.json`) and dependency graph (`links.json`). Each project gets its own folder with metadata, lane orderings, and one file per roadmap item in `items/`. External suggestions go into `suggestions/`, and completed or archived projects move into dedicated folders. For more on project organization, see this article.

This structure ensures that every artifact is inspectable, portable, and interoperable. It acts as a shared language and expectation for any tool or user interacting with the data. By adhering to this structure, systems can reliably read, interpret, and modify project data without proprietary dependencies.

Why is this critical? Because it makes the entire data ecosystem transparent and adaptable. Developers can add new features or integrations by simply respecting the folder and file conventions. This explicit structure reduces ambiguity, prevents data corruption, and facilitates collaboration across diverse tools and workflows.

For example, if you want to integrate with another app, just read or write the JSON files directly. No API, no middleware, no lock-in. This openness fosters innovation and ensures your data remains accessible, no matter what tools you choose to use.

Making Files Safe: Atomic Writes and Forward Compatibility

Handling files safely isn’t just about writing them—it’s about doing it atomically. Threlmark writes to temp files then renames, so crashes or interruptions never corrupt data. This atomic operation guarantees that a file is either fully written or unchanged, avoiding partial or corrupted states. It’s a simple yet crucial safeguard that mimics the reliability of database transactions in a file-based system. To learn more about safe file operations, visit this guide.

Beyond safety, Threlmark employs a tolerant merge approach. When reading a file, it applies defaults for missing fields and preserves unknown keys. This strategy allows newer versions of the system or external tools to add extra data without breaking compatibility with older versions. It effectively future-proofs your data, enabling seamless upgrades and extensions without risking data loss or corruption.

This pattern makes your data resilient to evolution. As your project grows and your tools evolve, the system adapts gracefully—adding new features, supporting new data types, and maintaining integrity even in the face of partial updates or external modifications.

For example, if a new property is introduced to a card in a future update, older versions will ignore unknown keys and apply defaults, ensuring compatibility and consistent behavior across versions. This forward compatibility reduces technical debt and makes long-term maintenance manageable.

How The Self-Healing Board Keeps Your Workflow Smooth

Threlmark’s lane board isn’t just a static list. It self-heals every time you open it. It compares the order of items in `board.json` against actual files in `items/` and repairs any mismatches.

This process involves checking for missing, extra, or misplaced items and automatically correcting discrepancies. If a user deletes a card directly from the filesystem, the next time the board loads, it recognizes this and removes it from the visual list. Conversely, if a new file appears in `items/`, the board updates to include it. This continuous synchronization ensures that your project view always reflects the real state of your data.

This self-healing mechanism reduces manual cleanup, prevents inconsistencies, and simplifies collaboration. It effectively creates a dynamic, living system that maintains integrity without constant manual intervention—saving time and reducing errors. In environments where data is frequently edited outside the main interface, this approach ensures your workflows remain smooth and trustworthy.

External Tools and AI Agents Play Nice with Just Files

Threlmark’s philosophy makes it easy for external tools or AI agents to participate without permission hassles. They just read and write files in the correct places.

For example, an AI assistant can scan `suggestions/`, pick a task, move it to `reports/` after completing, and update its status—all by manipulating plain JSON files.

This openness means integrations can happen seamlessly, encouraging a vibrant ecosystem of tools that respect the same contract. Because the data is stored in standard, human-readable JSON files, any system that understands JSON can interact with it—no special SDKs or APIs needed. This fosters innovation, reduces barriers to integration, and empowers users to craft workflows tailored to their needs.

What This Means for You: Portable, Private, and Resilient Data

When your data lives on your disk in plain files, you hold the keys. You can back it up, sync it with other devices, or migrate it anywhere—no vendor lock-in. This means your data isn’t tied to a specific cloud provider or platform, giving you full control over your digital assets.

Furthermore, your data remains private because it’s stored locally or within your trusted network. There’s no need to expose sensitive information to third-party cloud services, reducing risk and maintaining compliance with privacy standards.

This approach shines in scenarios like working offline in remote locations, handling sensitive projects, or when you prefer to manage your data without external dependencies. It provides peace of mind, knowing you can always access, modify, and secure your data without relying on external infrastructure. Plus, it simplifies disaster recovery—just copy your folder, and your entire project is preserved intact.

Imagine being in a remote cabin, working on your project without internet. Your data remains accessible, safe, and ready to sync once you reconnect, ensuring continuous productivity and control.

What Are the Real Tradeoffs? When Local-First Might Not Be Perfect

While local-first architecture offers many perks, it’s not a silver bullet. Managing conflicts, especially in multi-user setups, can get tricky. Synchronization requires careful handling, and some real-time applications might still prefer cloud-based consistency.

For example, a team collaborating across continents might face sync conflicts if not managed carefully. Threlmark’s model shines brightest when offline access, data control, and resilience matter most.

It’s about choosing the right tool for the job—local-first isn’t always the best for ultra-real-time, globally synchronized apps, but it’s unbeatable for privacy-focused, offline-capable workflows. The tradeoff is that you need to plan for conflict resolution and synchronization strategies, which can add complexity in multi-user scenarios. If your project requires instant data consistency across multiple locations, a cloud-based solution might be more straightforward. However, if sovereignty, privacy, and offline access are priorities, the benefits of local-first outweigh these challenges.

Frequently Asked Questions

How does Threlmark handle conflicts when multiple tools update files at once?

Threlmark uses atomic writes and separate files for each item. If two tools update different files, no conflict occurs. For concurrent updates to the same file, it relies on read-merge-write patterns that preserve data integrity and allow for conflict resolution without locks.

Can I use Threlmark with my existing tools or workflows?

Absolutely. Since Threlmark stores everything as plain JSON files, any tool that can read or write JSON can participate. You can manually edit, sync, or automate your workflow without vendor lock-in, making it highly flexible.

What happens if I lose my files or move my directory?

Because your data is stored in plain files, simply copying or backing up the directory preserves your entire project state. Moving the folder to another device or syncing it via Dropbox or Syncthing keeps your data intact and portable.

Is this approach suitable for team collaboration?

It works well for teams that can handle conflict resolution and offline workflows. For real-time, multi-user editing, additional synchronization strategies are needed. But for personal projects or asynchronous work, it’s a powerful, resilient choice.

Where can I learn more about Threlmark’s architecture?

Check out the official repository and website, including the [Threlmark GitHub repo](https://github.com/MeyerThorsten/threlmark) and [threlmark.com](https://threlmark.com). For deeper insights, Thorsten Meyer’s [personal site](https://thorstenmeyerai.com/) offers additional context and updates.

Conclusion

Treat your data like a living, breathing entity—stored on your disk, safe from the chaos of the cloud. Threlmark’s architecture shows how simple, transparent files can power resilient, privacy-first workflows. It’s a reminder that sometimes, the simplest solutions are the most powerful.

Next time you think about data storage, ask yourself: does my system trust the disk as the true record? If not, maybe it’s time for a fresh perspective.