Imagine a project management tool that works perfectly offline, stays lightning-fast, and never locks you into a single vendor or platform. That’s the promise of Threlmark’s architecture. It’s a bold twist on how we usually think about data—here, the disk isn’t just a storage medium; it’s the contract, the API, and the backbone of the entire system.

This isn’t just about saving files. It’s about rethinking how tools communicate, how data flows, and how external apps can participate without permission slips or complex integrations. In this article, you’ll see how treating disk as the single source of truth unlocks new levels of simplicity, resilience, and openness.

Why Making Disk the Single Source of Truth Changes Everything

In Threlmark, the disk isn’t just a backup or storage layer. It’s the contract that all tools, users, and AI agents rely on. This means your files, not a database, define what’s true. When you open Threlmark, it reads from `~/.threlmark`, pulling in JSON files that describe every project, task, and relationship.

For example, each project has its own folder with a `project.json`, while each task or card lives as an individual file in `items/`. No centralized database, no API server. Just files. This approach simplifies things: you can open a terminal, `cat` a file, and see exactly what’s stored. Want to migrate? Just copy the folder. Need to debug? Diff the files. It’s transparency on steroids.

According to Threlmark creator Thorsten Meyer, this design ensures that all external tools can join in—no API keys, no special permissions. They just read and write files, making the system open and flexible. That’s a game-changer for multi-tool workflows and collaborative projects.

How Threlmark’s File Layout Acts as a Contract — No Lock-In

Threlmark’s folder structure is more than organization; it’s a contract that guarantees everyone sees the same picture. At the root, you find `threlmark.json` for the overall setup, and `links.json` for dependencies. Each project lives in its own folder with files like `project.json`, `board.json`, and individual item files in `items/`.

Shared cards are stored under `shared/items/`, and old projects go into `archive/`. External suggestions land in `suggestions/`, and reports from AI agents go into `reports/`. Every file can be inspected, diffed, and backed up. No special database schema, no proprietary API—just files.

This structure ensures that data remains portable, open, and easily migrated. Want to switch to another tool? Copy the entire folder. Need to audit? Diff the files. This openness removes vendor lock-in and lets your workflow evolve naturally.

Making File Updates Safe and Atomic — No Corruption Risks

Using files as a database sounds risky—crashes, partial writes, data corruption. Threlmark avoids this with two key patterns: atomic writes and tolerant merge. When updating a file, it first writes to a temporary file, then renames it. Because `rename()` is atomic on the filesystem, it guarantees no corruption occurs—even during crashes.

For example, updating a task involves reading the current file, merging in changes, then atomically replacing it. This way, external tools can update individual cards without risking race conditions or partial states. It’s a simple, reliable way to keep data consistent.

Thorsten Meyer emphasizes that this pattern makes file-based state just as safe as a database—without the complexity.

One File Per Card — How It Solves Concurrency and Keeps Things Simple

Imagine editing a big JSON array for your roadmap. Every change risks overwriting others or causing conflicts. Threlmark solves this by storing each card in its own file, like `items/.json`. This way, multiple external tools can update different cards simultaneously without clashing.

Lane order? Stored in `board.json` as ordered lists of IDs. The clever trick: every time you read `board.json`, Threlmark reconciles it against actual items, healing any inconsistencies. If a card is deleted but still listed in the lane, it quietly drops out on read.

During collaboration, this approach minimizes race conditions, simplifies conflict resolution, and keeps the data model lean. It’s a practical way to avoid locking mechanisms and keep external integrations straightforward.

Flow and External Tools: How the Architecture Supports AI and Collaboration

Threlmark isn’t just a static tracker. Its architecture encourages external tools and AI agents to participate naturally. External apps can add suggestions, move cards, and report back, all by writing files into specific folders.

For example, an AI agent can scan the `suggestions/` folder for new ideas, pick one, update the corresponding item file, then move it to `reports/` after completing the work. This loop happens seamlessly because everything is just files.

By making the data open and the process stateless, Threlmark allows AI agents to close their own loops—making automation more reliable and flexible. The result? A system that evolves with your tools, not against them.

What You Can Do Today — Practical Tips for Adopting a Disk-First Mindset

• Start by organizing your data as JSON files in a dedicated folder. Think of it as your system’s brain—not just backup, but the actual source of truth.
• Use `rename()`-style atomic writes for all updates to prevent corruption, especially if you’re dealing with multiple tools or scripts.
• Design your app or tools to read, merge, and write individual files rather than entire arrays or databases. This keeps concurrency simple.
• Leverage open formats and folder structures to make migration, debugging, and external tool integration straightforward.
• Encourage external scripts or AI agents to participate by simply reading and writing files, no permissions or APIs needed.

Key Takeaways: How Threlmark’s Design Inspires New Ways to Build Tools

• The disk is the contract—files are the API, making data transparent, portable, and lock-in free.
• One file per item simplifies concurrency, reduces conflicts, and enables external tools to operate independently.
• Atomic file writes prevent corruption, even during crashes, ensuring system reliability.
• Reconciliation on read keeps the system consistent without locks or complex sync protocols.
• Open formats and folder structures foster collaboration, automation, and migration—future-proofing your workflows.

Frequently Asked Questions

What does ‘disk is the contract’ mean in practice?

It means that all data interactions happen directly through files on disk, not through a database or API. The files serve as the definitive record, making data transparent, portable, and easy to inspect or migrate.

How does Threlmark handle conflicts when multiple tools update the same file?

Threlmark uses atomic writes and merge strategies that prevent corruption. Each item has its own file, so updates are collision-free, and conflicts are minimized. Reconciliation on read helps keep data consistent without locking.

Is this approach suitable for large-scale projects?

For very large projects, file-based storage can become unwieldy, but for many collaboration and automation scenarios, it offers unmatched simplicity and resilience. It’s ideal for tools emphasizing openness, portability, and offline-first workflows.

How do external AI agents participate without permissions or APIs?

They simply read, write, and move files within designated folders like `suggestions/` and `reports/`. This open approach removes barriers, allowing AI and scripts to integrate effortlessly.

What are the main tradeoffs of a disk-first system?

While it simplifies data management and boosts resilience, it requires careful handling of conflicts, versioning, and sync. It’s best suited for scenarios where transparency, portability, and offline work matter most.

Conclusion

Thinking of disk as the contract isn’t just a clever trick; it’s a new way to build resilient, open, and flexible software. By treating files as the ultimate authority, you remove complexity, foster collaboration, and set the stage for automation that just works.

Next time you design a tool, ask yourself: could the disk be the API? The answer might just unlock a simpler, smarter future for your projects.