Imagine an app where your entire project data lives on your disk, untouched by servers or cloud services. It’s fast, reliable, and always available—offline or online. That’s the core idea behind Threlmark’s local-first architecture: the disk isn’t just storage; it’s the contract that defines your system’s entire state.

This approach flips the usual client-server model on its head. Instead of relying on a remote database, Threlmark treats your filesystem as the primary source of truth. It’s a design choice that’s simple in theory but powerful in practice, making your data more portable, safer, and more flexible than traditional tools. Disk is the contract.

Key Takeaways

• Treat your disk as the primary contract—store each task or piece of data as a separate, inspectable JSON file.
• Use atomic file writes to prevent corruption, ensuring your data stays safe even during crashes.
• Design your system to be self-healing—reconcile lane order and other metadata on each load.
• Separate local work from sync processes, so your app remains fast and responsive even offline.
• Handle conflicts with versioning and user review, allowing smooth collaboration across devices.

What does ‘disk is the contract’ really mean?

At its core, ‘disk is the contract’ means your data lives on your device’s filesystem, and that layout directly defines how the app works. Every file, from project configs to individual task cards, is a piece of the system’s truth.

For example, Threlmark stores each task as a separate JSON file inside an ‘items/’ folder. This simple structure lets you open, edit, or back up your data with just a file explorer or a command line. The app trusts these files more than any in-memory database.

This approach is like having a contract written in plain text—clear, inspectable, and easy to change without breaking the system. It’s a deliberate choice that keeps the system transparent and flexible. Disk is the contract.

Why does this matter? Because in traditional apps, data stored in databases is often opaque and locked behind APIs. By making the filesystem the contract, Threlmark emphasizes transparency, enabling users and developers to understand, modify, and troubleshoot their data directly. This reduces vendor lock-in and fosters a more open, adaptable ecosystem. Disk is the contract.

Why making disk the source of truth boosts your productivity

When your disk is the single source of truth, your app becomes instantly responsive. No waiting for server responses, no error states caused by network blips. You work directly on files that are always available.

Imagine editing a task on a train, with no internet. Your changes save instantly on your disk—no lag, no disconnect. Later, when online, Threlmark syncs your updates seamlessly, but your work isn’t blocked or delayed.

This local-first approach means your data is always accessible, even if the cloud or server crashes. It’s like having a notebook that’s always with you—no dependency on external systems.

What are the implications of this? By removing reliance on remote servers for immediate data access, you reduce latency and potential points of failure, resulting in a faster, more reliable user experience. However, it also means that the system must handle conflicts and synchronization carefully—if multiple devices modify the same data offline, they can create conflicts that need resolution. This tradeoff favors resilience and responsiveness but requires thoughtful conflict management strategies to maintain consistency across devices.

How Threlmark keeps data safe and consistent with files

Threlmark uses two key patterns to keep your data safe: atomic writes and tolerant read-merge cycles. Disk is the contract means every change goes to a temp file then renames itself, so corruption is impossible—even if your computer crashes mid-write.

For example, when you update a task, the system writes to a temporary file and then swaps it in. It’s like changing a page in a book, then replacing the old page all at once.

The read-merge approach makes the system tolerant to partial updates and future changes. Unknown fields or new data structures are preserved untouched, ensuring compatibility even as the system evolves.

Why do these methods matter? They enable your data to survive unexpected failures and software updates without corruption or data loss. This reliability is crucial for a system that relies on the filesystem, which can be vulnerable to interruptions. The tradeoff is that implementing atomic and tolerant operations adds complexity to the codebase, but it results in a much more robust system that maintains integrity over time.

One file per item: how it prevents conflicts and makes updates smooth

Instead of having one giant JSON file for a project, Threlmark keeps each task or card in its own file. This way, external tools can update a single card without touching everything else. Disk is the contract.

For example, if you use a script to add a new task, it just creates a new file or updates an existing one. No locks needed, no clobbering other updates.

This design reduces conflicts, especially when multiple tools or devices edit data simultaneously. It’s like having many small, independent notebooks instead of one big ledger.

What are the tradeoffs? While this approach makes concurrent editing easier and conflicts less likely, it also means managing many files, which could become cumbersome at scale. Developers need to implement efficient file indexing and change detection, but the payoff is a system that scales well with multiple sources of updates and minimizes conflicts, leading to smoother collaboration.

How the board self-heals and stays consistent

The lane order in Threlmark is stored separately from individual items, in a ‘board.json’ file. Every time you load the board, it checks which items still exist and reconciles missing ones. Disk is the contract.

For example, if you delete a task, the lane order updates automatically. If an item is moved or removed, the system adjusts the lane list during each read, keeping everything consistent without manual cleanup.

This self-healing property keeps your workspace tidy and always reflects the true state of your data, even amid concurrent edits or deletions.

Why does this matter? Because it reduces the need for manual data cleanup and prevents dangling references that could cause errors or confusion. The tradeoff is that implementing self-healing logic requires additional checks and reconciliation code, but it results in a more resilient and user-friendly system that maintains integrity over time.

Syncing without breaking the user experience

Threlmark’s local-first design makes syncing straightforward and non-intrusive. Changes are stored locally immediately, then synced in the background when connected.

For instance, adding a card on your phone updates the local file instantly. When your laptop is back online, it picks up that change seamlessly, without interrupting your workflow.

This separation of local work and sync allows the app to stay fast and responsive, even in spotty network conditions. It’s like having a notebook that auto-updates across devices without you noticing the sync process.

Why is this important? Because it ensures that users experience minimal disruption during sync, maintaining productivity and a smooth workflow. The tradeoff is that conflict resolution during sync can become complex if multiple devices change the same data offline, requiring careful conflict management strategies to ensure data integrity and user trust.

Handling conflicts and ensuring smooth collaboration

Conflicts happen when two devices edit the same data differently. Threlmark handles this by preserving all versions and letting you resolve conflicts manually or automatically.

For example, if two people change the same task, the system records both versions and flags them for review. You can see what changed and decide which update to keep.

This approach favors eventual consistency, allowing multiple devices to work offline and sync later without losing data.

What are the implications? Because conflicts are stored as separate versions, users have the opportunity to review and resolve discrepancies, preventing silent overwrites and data corruption. The tradeoff is that conflict resolution can sometimes be manual or require user intervention, which may slow down workflows but ultimately ensures data accuracy and trustworthiness across devices.

When local-first isn’t the right choice

While powerful, local-first systems aren’t perfect for every scenario. If you need strict, real-time multi-user consistency, or handle massive write loads, this approach adds complexity.

For example, a stock trading platform requires instant, perfectly synchronized data—local-first might introduce delays and conflicts.

In such cases, traditional client-server models with strong consistency are better suited, even if they sacrifice some offline capability.

Understanding these tradeoffs helps you decide whether local-first is appropriate for your project. It’s essential to evaluate your specific needs for immediacy, consistency, and complexity before choosing this architecture.

Frequently Asked Questions

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

It means your application’s data is stored directly in files on your disk, and these files define the system’s state. Everything from task cards to project configs is in plain JSON files, making the data transparent, portable, and safe from in-memory crashes.

How is local-first different from offline-first?

Offline-first emphasizes working without internet, while local-first treats the device’s disk as the primary source of truth. Even when offline, your data is accessible and modifiable. Syncs happen later, when connected, ensuring seamless collaboration and resilience.

What happens when two devices edit the same data?

The system records each version and flags conflicts for review. This approach prioritizes eventual consistency, allowing offline edits to sync later without data loss. You resolve conflicts manually or let the system merge changes intelligently.

How do conflicts get resolved during sync?

Conflicts are stored as separate versions, and you can review and resolve them manually. Some systems auto-merge non-overlapping changes, but complex conflicts usually require your input to choose the best version.

Is local-first safe for sensitive or regulated data?

Yes, because data stays on your device unless you choose to sync. Plus, you can encrypt files or control sync timing. This local control often makes local-first safer than cloud-only options for sensitive data.

Conclusion

Threlmark’s approach proves that the simplest idea—making disk the system’s contract—can unlock resilience, portability, and a better user experience. It’s a reminder that sometimes, the most straightforward design choices lead to the most powerful tools.

When data lives on your disk, you’re not just storing information—you’re defining how your system works, evolves, and collaborates. That simple act rewires everything about how you build and think about digital tools.