Imagine working on a project where your data isn’t locked inside a cloud or a database. It’s right there on your disk, just like a physical notebook you can open, read, and edit. That’s the core idea behind Threlmark’s local-first architecture — it treats the disk as the single source of truth, making everything simple, fast, and resilient. Learn more about Threlmark’s architecture.

This approach might sound old-school, but it’s actually a powerful shift. No servers, no fancy sync layers — just files. And those files tell the whole story. Today, I’ll show you how this design works, why it’s a game-changer, and what it means for anyone building complex apps or managing multiple projects offline and online. Discover more about local-first systems.

Key Takeaways

• Treat the disk as the contract: plain JSON files are the single source of truth, making data transparent and portable.
• Use one file per item to enable safe, concurrent updates without locking or complex merge conflicts.
• Atomic writes and tolerant merging keep your data safe and forward-compatible, even with manual edits.
• The self-healing board architecture ensures consistency without manual sync, perfect for offline workflows.
• This approach simplifies collaboration, reduces dependencies, and opens the door to AI automation.

Why the Disk Is the Single Source of Truth in Threlmark

Threlmark’s bold move is to let the disk be the contract — the ultimate authority. Instead of a database or cloud service, all data lives in plain JSON files. This makes the system incredibly transparent and flexible. You can open any file, see the exact state, and even tweak it manually if needed. Read more about disk as the contract.

For example, every roadmap card is a separate file in the `items/` folder. When you move a card, you just update that one file. No need for complex locking or transactions. This simplicity means you can work offline, in any environment, and still trust your data as the definitive version.

According to Threlmark’s creator, this approach reduces bugs, improves interoperability, and ensures your data is always portable — just copy the folder or sync it with Dropbox or git, and you’re done. No vendor lock-in, no special SDKs, just plain files.

How Threlmark’s File Layout Supports Seamless Collaboration

The layout isn’t just a random collection of files. It’s a carefully designed contract. At the root, you find `threlmark.json` and `links.json`. Each project has its own folder with `project.json`, `board.json`, and one file per card in `items/`. Shared cards, suggestions, handoffs, and reports all get their own dedicated folders. Explore more on file layout for collaboration.

Imagine working on a multi-team project. Each team updates their own card files. When you open Threlmark, it reads all those files, sees what’s missing or out of sync, and automatically heals the board. No conflicts, no lost updates, no complicated merge conflicts.

This self-healing design makes it easy to integrate external tools or even manually edit files. You can trust that the system always reflects the true state of your work — because the files themselves are the truth.

Why One File per Item Beats a Big Array of Cards

Instead of a single `roadmap.json` with all cards listed inside, Threlmark uses one file per item. This tiny change drastically improves concurrency. Multiple external tools can update different cards simultaneously without clobbering each other.

For example, if you’re working on a big feature, you might update its file while a teammate updates another. Because each update is atomic, there’s no race condition. The `items/` folder becomes a collection of tiny, independent files that always stay consistent.

And if a card gets deleted, just remove the file. The system automatically recognizes missing files as completed or archived items during the next read. It’s like a living, breathing collection of tiny notebooks, each representing a single idea or task.

Making the System Safe: Atomic Writes and Tolerant Merging

Working with files might sound risky, but Threlmark takes careful steps to keep everything safe. Every write to a file happens through an atomic process: write to a temp file and then rename it. This way, crashes or interruptions leave your data intact. Learn about safe file operations.

When updating a card, Threlmark reads the current file, merges changes, and writes back. It preserves important fields like `id` and `createdAt`, updates timestamps, and keeps unknown data untouched. This tolerant merge ensures forward compatibility.

For example, if a newer tool adds a new field, older tools will ignore it but won’t destroy it. The data just grows naturally, like a conversation that never loses its context.

How the Board Self-Heals and Keeps Everything in Sync

The lane order isn’t stored as a big list. Instead, it lives in `board.json` as ordered IDs. When you load the board, Threlmark cross-checks the actual item files and fixes any discrepancies. Missing items disappear from the view, and new ones show up automatically.

This self-healing makes the entire system resilient. If someone deletes a card manually or an external tool adds a new one, the board updates itself on the next read. No manual sync needed — just trust the files.

Imagine a team working across different devices. They add, move, or archive tasks. The system keeps everything consistent, regardless of interruptions or concurrent edits.

The Power of Portable, Interoperable Data

Because everything is plain JSON files, your data is inherently portable. You can back it up, version it, or migrate it with simple file operations. No proprietary database or cloud service locks you in. See how portable data supports remote work.

Need to move your project to a different machine? Just copy the entire folder. Want to integrate with another tool? Read and write the files directly.

This flexibility is a core advantage, especially for teams working across multiple environments or needing offline-first reliability.

Real-World Example: How Threlmark Supports a Remote Team

Picture a remote team using Threlmark on their laptops, tablets, and desktops. Each member edits their parts locally, updating individual item files. When they sync, the system reconciles all changes seamlessly.

One developer adds a new feature card while another archives an old task. Threlmark reads all the files, heals inconsistencies, and updates the board instantly. No server needed, no conflicts — just a shared folder.

This setup proves that local-first isn’t just theoretical. It’s practical, empowering teams to stay productive regardless of network conditions.

What’s Next? How to Build Your Own Disk-First App

If you’re inspired, here are the key steps to start:

1. Design a folder structure where each piece of data gets its own file.
2. Implement atomic file writes to prevent corruption.
3. Use tolerant merge strategies to update files without losing unknown data.
4. Create self-healing read functions that reconcile files and fix inconsistencies.
5. Build your UI to read from and write to these files directly, avoiding complex databases.

Want to see how Threlmark does it? Check out their codebase on GitHub or try their demo at threlmark.com. The principles are simple, but the impact is profound.

Frequently Asked Questions

What does ‘disk is the contract’ really mean?

It means that all data lives in plain files on your disk, and these files are the definitive source of truth. No databases or cloud services are needed; the files themselves tell the entire story of your project.

How does Threlmark handle conflicts when multiple tools update files simultaneously?

Threlmark uses one file per item with atomic writes. This setup prevents race conditions. Updates merge intelligently, preserving unknown data and updating timestamps, ensuring consistency even during concurrent edits.

Can I manually edit the files without breaking the system?

Yes. Threlmark’s tolerant merge strategy preserves unknown keys and defaults missing fields. Manual edits won’t break the data, and the system will reconcile changes on each read, keeping everything in sync.

What are the benefits of this approach over traditional databases?

Files are portable, inspectable, and lock-free. You can back them up or migrate easily. Plus, it’s resilient offline, simple to understand, and compatible with any tool that can read/write JSON.

Is this approach suitable for large teams or complex projects?

Absolutely. Using one file per item scales well, and the self-healing architecture keeps everything consistent. It’s especially useful for distributed teams working across multiple devices or slow networks.

Conclusion

Threlmark’s local-first architecture turns your disk into the ultimate project hub. It’s a simple idea with big implications: your data, always accessible, always trustworthy, ready for AI-powered workflows.

If you want to build resilient, collaborative tools that work offline and online, starting with a disk as the contract might just be the smartest move you make. Your future self will thank you — and the next time you look at a folder full of JSON files, you’ll see a tiny universe of possibility.