Imagine working on your project board without needing an internet connection, knowing your data is safe and instantly accessible. That’s the power of Threlmark’s approach — it puts the disk at the heart of everything, similar to how Disk Is the Contract: Inside Threlmark’s Local-First Architecture emphasizes the importance of local storage as the central source of truth.

This isn’t just about saving files; it’s about building a system where your device’s local storage becomes the ultimate source of truth. No cloud, no central server, just simple, reliable, and portable data. It’s a shift that redefines how we think about project management, AI, and collaboration in today’s offline and multi-device world, as discussed in this article on local-first architecture.

Key Takeaways

• Treat the disk as the single source of truth by organizing data into individual, inspectable JSON files.
• Atomic writes and tolerant merge strategies make file-based systems safe and adaptable for future changes.
• Using one file per item reduces race conditions, improves concurrency, and allows self-healing of data structures.
• Offline work and multi-device sync are natural benefits of a local-first architecture that always reads from local disk.
• Open, plain-text data fosters interoperability and user control, avoiding vendor lock-in.

Why the disk is the ultimate contract for your data

In Threlmark’s world, the disk isn’t just storage — it’s the contract. Every file, every folder, is a piece of the truth. When you open your project, you’re reading the same files that any external tool can write to.

For example, a project’s roadmap lives in items/. Each card is a simple JSON file, not a complex database. This makes the data transparent, portable, and safe from lock-in. If your system crashes or you switch devices, your data stays intact because it’s always stored on disk, ready to be read or updated without fuss, as explained in this detailed overview of local-first architecture.

How Threlmark’s file layout turns the disk into a living contract

Threlmark’s architecture is a carefully designed folder structure, where each piece of data lives in its own file. The root folder contains a manifest (threlmark.json) and a dependency graph (links.json).

Each project has its own folder with JSON files for metadata, lane order, and WIP limits. The key part: each roadmap card gets a dedicated file in items/. External suggestions go into suggestions/, and recorded handoffs sit in handoffs/.

This design ensures every artifact is inspectable, portable, and compatible with any tool that reads files — making the disk the undeniable source of truth, similar to concepts discussed in this article on local-first systems.

Making file-based state safe and reliable

Using files as a database sounds risky — but Threlmark uses two proven patterns to keep data safe. First, **atomic writes**. Every update writes to a temp file, then atomically renames it over the original. This way, crashes never corrupt data.

Second, **read-merge-write**. When updating, the system reads the current file, spreads in the changes, preserves essential fields like id and createdAt, bumps updatedAt, and writes back atomically. This approach ensures compatibility across different tools and future updates.

One file per item: the secret to concurrency and healing

Instead of a big roadmap.json list, Threlmark uses one file per item. This means each card can be updated independently, avoiding race conditions. When multiple tools or devices change data, they don’t step on each other.

Plus, the system automatically reconciles the lane order on read. If a card disappears or is moved, the board heals itself. This self-healing behavior keeps your view consistent without manual intervention.

How Threlmark’s architecture supports offline work and multi-device sync

Because all data lives on disk, you can work offline without a hitch. When your device reconnects, Threlmark syncs changes across devices by merging committed updates. This background process is lightweight and reliable.

Imagine editing a card on your laptop while offline, then seeing it updated on your tablet hours later. The system handles conflicts gracefully, using change graphs and deterministic resolution to keep everything in sync.

Interoperability and open data: why it matters

Threlmark’s file-based approach isn’t locked behind a proprietary database. Any tool or script can read or write data directly. Want to build your own plugin or integrate with another app? Just read the JSON files.

This openness makes your data truly portable — no vendor lock-in, no obscure formats. Plus, you can back up or migrate your data with common file operations, as highlighted in this piece on data portability.

Real-world example: managing a complex multi-project setup

Imagine juggling three projects: a website redesign, a marketing campaign, and a product launch. Each has its own folder, with individual cards for tasks, ideas, and bugs. When a developer updates a bug card on their laptop, the change immediately becomes part of the shared data, illustrating the benefits of local-first architecture.

Later, when they check their tablet, the latest updates are there — no manual sync needed. This seamless flow is possible because of the file-per-card structure and the local-first philosophy.

What developers gain by treating the disk as the source of truth

Developers love simplicity. Threlmark’s approach reduces complexity by removing the need for a database. It’s just files, atomic operations, and a clear contract.

This means easier backups, straightforward debugging, and fewer hidden failure modes. Plus, it’s easier to extend or adapt as needs evolve.

Practical tips for building your own local-first app

1. Use atomic file operations for all writes.
2. Design your data model as independent files.
3. Implement read-merge-write updates with tolerant normalization.
4. Build a self-healing reading process that reconiles inconsistencies.
5. Ensure your app can work offline and sync changes in the background.

Frequently Asked Questions

What does ‘local-first’ mean in plain English?

Local-first means your data is stored primarily on your device, not in the cloud. The app works offline, and cloud sync is a background process that keeps multiple devices in step.

How does sync work when devices reconnect?

When devices come back online, Threlmark merges changes by tracking a graph of updates, resolving conflicts deterministically. It’s like piecing together a puzzle from different angles without losing data.

What happens if two people edit the same card at once?

Threlmark’s system uses change graphs and rules to reconcile conflicts automatically. The latest changes are merged, preserving both edits where possible, and alerting you if manual resolution is needed.

Can local-first architecture power complex products, not just notes or Kanban boards?

Yes. By designing data as independent files and supporting background sync, local-first can scale to complex apps like CRMs, project management tools, and collaborative platforms.

How do you ensure data security if everything is stored locally?

You can encrypt your files and control who has access. Local storage reduces attack surfaces, and with proper encryption, your data stays private even if devices are lost or stolen.

Conclusion

Threlmark’s approach shows that the simplest solution — the disk as the contract — can be incredibly powerful. It offers resilience, flexibility, and a seamless experience for multi-device workflows.

Next time you build or choose a project tool, ask yourself: are you making the disk the contract? If not, consider how this approach could simplify and strengthen your work.