Imagine an app where your data lives right on your device, not on some distant server. Your work is fast, private, and always accessible, even offline. That’s the core of Threlmark’s local-first architecture — a simple idea with profound implications.

Here, disk isn’t just storage, it’s the contract. It’s the contract — the single source of truth that guides every decision. This article pulls back the curtain on how Threlmark makes this happen, from file layout to conflict resolution, and why it matters for your next app.

Key Takeaways

• Treat the disk layout as the API: design your app to read/write files directly, making data transparent and portable.
• Use atomic write patterns to keep your file-based data safe from corruption during crashes or concurrent updates.
• Single-file per item simplifies conflict resolution and makes syncing straightforward, even in offline scenarios.
• Syncing is a decentralized background process—detect changes, compare files, merge conflicts, and update all devices automatically.
• Prioritize local storage to boost privacy, security, and resilience, reducing dependence on centralized servers.

Why Treat Disk Storage as the Ultimate Contract

Threlmark’s approach flips the traditional model. Instead of relying on a server or cloud as the master copy, the disk is the primary source of truth. This means your data lives in JSON files, organized in a way that any tool can read or write without special permissions. Instead of relying on a server or cloud as the master copy, the disk is the primary source of truth. This means your data lives in JSON files, organized in a way that any tool can read or write without special permissions.

For example, a project’s roadmap is just a folder with files like `project.json` and individual cards as separate files. When you update a card, you simply overwrite its file. This makes the system incredibly transparent and portable — just copy the folder, and you’ve got your entire project.

This design choice has huge benefits: inspectability, no lock-in, interoperability, and resilience. If your device crashes, your data is still there, ready to be synced or recovered. It’s a simple, reliable contract that everyone can understand.

Inside the File Layout: How the System Organizes Everything

Threlmark’s file layout is a well-defined contract that structures data into different folders and files. At the top level, you’ll find `threlmark.json` (the manifest) and `links.json` (dependency graph). Each project has its folder with `project.json` and `board.json`, along with individual item files in `items/`.

For example, a card about a feature might be stored as `items/feature123.json`. Changes to that card are simply written to that file. External suggestions go into `suggestions/`, and completed tasks move to `archive/`. This organization makes everything easy to inspect, back up, or migrate.

It’s a contract that any tool can join. Just read or write files—no APIs, no databases, no special permissions. The layout becomes a shared language for all your tools, from AI to CLI helpers.

Making File-Based State Safe and Reliable

Using files as the source of truth sounds risky, but Threlmark uses two key patterns to keep it safe. For more details, see this explanation of local-first architecture. First, **atomic writes**: every update writes to a temp file, then renames it over the original. This guarantees that no partial file ever corrupts your data. Imagine saving a document — you don’t want half a page missing, right?

Second, **read-merge-write**: updates read the current file, merge in changes, and write back atomically. This allows external tools to change individual files without clobbering each other, even during concurrent edits. It’s like editing a chapter in a shared document without messing up everyone else’s work.

These patterns turn a filesystem into a safe, distributed database—without the complexity of a server or lock manager.

How the System Handles Concurrency and Conflicts

Concurrency is a challenge when each file is a standalone artifact. Threlmark’s approach is similar to websites that use file-based content management. Threlmark solves this by using **one file per item**. Instead of a big list, each card is its own JSON file. When two devices update separate files, there’s no conflict—just overwrite or merge when syncing.

For conflicts—say, two devices edit the same card simultaneously—Threlmark relies on merge strategies like timestamps and versioning. It’s similar to how Git handles concurrent changes: last write wins, or you can manually resolve conflicts if needed.

This approach simplifies sync. Instead of complex conflict resolution algorithms, you just merge files based on their metadata, keeping everything straightforward and predictable.

Syncing Without a Central Server—How It Really Works

Threlmark treats syncing as a background process that compares files across devices. Learn more about how this works in this detailed article. When your device reconnects to Wi-Fi, it automatically detects changes in the shared folder. Files are then pushed or pulled, and conflicts are resolved based on timestamps or merge rules.

It’s like a Dropbox folder that keeps itself up-to-date, but with custom logic built-in. No central server is needed—just a shared folder or cloud storage that everyone can access. This makes your app resilient and flexible.

For example, you might work on your laptop offline for hours. When you reconnect, your changes seamlessly sync to your phone and desktop, with conflicts merged or flagged for review.

Why Local-First and Disk as the Contract Matter for Privacy and Security

When your data lives primarily on your device, privacy naturally improves. Threlmark’s system keeps data local unless explicitly shared or synced. This reduces attack vectors and keeps sensitive info out of the cloud unless you choose to share.

Plus, with end-to-end encryption, the data on disk remains secure—even if someone steals your device. Threlmark’s architecture makes it easier to implement encryption because the data is already local and isolated.

Imagine a team managing confidential project files. They can work offline, keep everything encrypted on disk, and only sync when they want to share updates. It’s a privacy-first approach that fits modern security expectations.

Business Benefits: Lower Costs and Greater Resilience

By making the device the primary data store, Threlmark reduces backend costs dramatically. No need for a giant server or cloud database—just a shared folder or sync layer. This cuts infrastructure expenses and simplifies scaling.

It also makes your app more resilient. If the internet drops, users keep working. When connectivity returns, sync happens automatically. That’s a huge win for reliability and user satisfaction.

For example, a team using Threlmark can work on a plane, offline, then sync when they land. No downtime, no data loss—just seamless productivity.

Real-World Examples and Implementation Patterns

Threlmark’s architecture draws on common local-first patterns like IndexedDB for browsers, filesystem storage for desktops, and CRDTs or commit graphs for conflict resolution. For instance, a web app might store each task as a separate IndexedDB record, then sync in the background.

In desktop apps, files stored in a folder like `~/.threlmark/` serve as the backbone. External tools or scripts can modify these files directly, making integrations straightforward.

Recent projects show how this pattern scales from simple to complex apps—like collaborative writing tools or project management systems—without relying heavily on servers.

Frequently Asked Questions

What does ‘disk is the contract’ actually mean?

It means the app’s data structure is stored directly on disk as files, and these files define the system’s state. The file layout becomes the single source of truth, making the system transparent, portable, and easy to sync or restore.

How is local-first different from offline-first?

Offline-first emphasizes the ability to work without network access, while local-first treats the device’s storage as the main data source. Local-first systems sync data across devices when connected, ensuring consistency and resilience.

How does syncing work if the device is the source of truth?

Syncing compares files across devices, detects changes via timestamps, and merges updates based on rules. It’s a background process that keeps all copies consistent without needing a central server.

What happens when two devices edit the same data at once?

Threlmark uses strategies like timestamps and merge rules—similar to Git—to resolve conflicts. Files are merged or last-writer-wins, keeping the system predictable and conflict-free.

Do local-first apps need a backend at all?

Not necessarily. The backend often acts only as a sync or backup layer, not the primary data store. This reduces costs and complexity, giving users more control and resilience.

Conclusion

Thinking of disk as the contract transforms how you build apps—more resilient, private, and flexible. It’s a simple shift that unlocks offline-first workflows and seamless multi-device sync.

Next time you design a system, ask yourself: can I make the disk the single source of truth? If so, you’re building for a future where your apps are faster, safer, and more user-controlled.