Imagine working on your project without needing a cloud or a remote server. Your data lives right on your disk, just like a notebook full of plain text. That’s the thinking behind Threlmark’s approach — the disk isn’t just where data is stored, it’s the core contract that defines how everything works.

This article peels back the layers of Threlmark’s design, showing how a simple on-disk JSON layout shapes the entire system. You’ll see why this approach makes offline work seamless, how it simplifies collaboration, and what tradeoffs it involves. If you’re curious about building resilient, portable apps that work everywhere, this deep dive is for you. Learn more about Threlmark’s local-first architecture.

Key Takeaways

• The on-disk JSON files are the system’s true source of truth, making data transparent and portable.
• Local-first design means your project remains accessible and editable even without an internet connection.
• Atomic file operations prevent corruption and race conditions, ensuring reliable data handling.
• Sync processes compare JSON files, resolving conflicts based on timestamps or rules, to keep data consistent.
• This architecture is best suited for solo work, small teams, or scenarios where transparency and offline capability matter most.

Why Threlmark’s Disk Is the Contract Changes Everything

In Threlmark, the disk isn’t just storage — it’s the blueprint of the entire system. Every file, folder, and JSON document is an authoritative declaration of state. This approach turns the traditional idea of a database on its head. Discover more about local-first data models.

For example, instead of a remote server holding all data, you keep your project info on your local disk. When you open Threlmark, it reads these files directly. Changes you make are immediately written to disk, not sent over the network. This means your data is always accessible, even when offline.

By making the disk layout the system’s contract, Threlmark guarantees that anyone or any tool can read, modify, and sync data without special permissions or proprietary formats. It’s like a shared language everyone speaks fluently.

This design choice emphasizes transparency and simplicity, but it also shifts some complexity to the developer’s shoulders. For instance, since the files are the source of truth, handling conflicts or data integrity relies heavily on well-defined file structures and protocols. This approach can reduce dependencies on external systems but requires rigorous discipline in managing file states, especially in collaborative environments. The tradeoff is that while it’s easier to understand and debug, it may demand more manual oversight during complex sync scenarios.

How the JSON Files Turn Your Disk Into a Living System

Threlmark’s data lives as plain JSON files arranged in a carefully designed directory structure. Each project, card, or dependency is a separate file — like individual pages in a well-organized filing cabinet.

For instance, every roadmap card gets its own `.json` file in the `items/` folder. Lane order? Stored in `board.json`. Cross-project links are in `links.json`. This makes every piece of data easy to find, edit, and back up.

What’s brilliant is that you can open any of these files with a text editor, see exactly what’s happening, and even fix problems manually if needed. The entire data model is human-readable and version-control friendly.

Deeply, this model allows for a high degree of transparency and control. Because each piece of data is a standalone JSON file, developers and users alike can quickly identify where a problem might be—be it a corrupted file, conflicting edits, or outdated information. This granular approach simplifies debugging and makes the system inherently compatible with version control systems like Git, encouraging a culture of transparency and accountability. Read more about managing JSON files in local-first systems.

Offline-First Means Instant Response and No Downtime

When your data is on disk, your app becomes lightning-fast. No waiting for remote server responses. You can add, modify, or delete cards instantly. Even if your internet drops, your workflow continues uninterrupted. Explore more about offline-first data management.

Take a developer working on a plane — they still see their project board, move cards, and jot notes without a hiccup. When they reconnect, Threlmark syncs changes seamlessly, merging updates across devices.

This local-first approach turns the app into a resilient workhorse, perfect for remote areas, airport lounges, or homes with shaky internet.

Beyond speed, this approach also offers a significant advantage in terms of data privacy and control. Since data never leaves the local environment unless explicitly shared, users retain full ownership and oversight. However, it also means that in the absence of a good sync strategy, conflicts can become more frequent or complex, especially if multiple devices are used simultaneously. The tradeoff is that while offline responsiveness is excellent, maintaining consistency across devices requires careful planning and conflict resolution strategies, which can add complexity as the system grows.

Sync and Conflict Resolution: Making Peace with Changes

Syncing in Threlmark is like a conversation between devices — they compare their JSON files and reconcile differences. Conflicts? They’re handled by rules that favor recent changes or prompt for manual resolution. Learn about conflict resolution in local-first systems.

Imagine two devices editing the same card. When they sync, Threlmark compares the `updatedAt` timestamps. The latest change wins, or sometimes, it flags a conflict for review. This keeps your data consistent without losing work.

It’s a delicate dance. The system relies on the fact that each change is a quick, atomic file update, making conflict detection straightforward and robust.

Deeply, this method emphasizes simplicity and reliability. By relying on atomic file operations and timestamp comparisons, Threlmark reduces the risk of corruption or partial updates. However, conflicts can still arise, especially in collaborative scenarios with offline edits. The system’s rules—favoring recent changes or prompting manual resolution—are designed to balance data integrity with user convenience. The tradeoff is that resolving conflicts manually can be time-consuming and may require user intervention, which might impact productivity in high-collaboration environments. Nonetheless, this approach offers a transparent and predictable conflict resolution process rooted in simple file comparisons, making it accessible and understandable to users and developers alike.

The Benefits of a File-Based, Portable Data Model

Using files as the source of truth makes your data inherently portable. Want to switch laptops? Copy the entire folder. Need to back up? Just save the folder. No vendor lock-in. See how file-based data models enhance portability. lock-in, no proprietary database formats.

Threlmark’s design also simplifies debugging. Curious about a card’s history? Just open its JSON file. Want to see the full roadmap? Browse the `ROADMAP.md` mirror. All data is transparent and easy to manage.

This portability is a game-changer for teams that value control and simplicity.

Deeply, this approach means that data portability and transparency are baked into the system. You’re not locked into a specific vendor or cloud provider—your data travels with you, unencumbered. This makes disaster recovery, migration, and inspection straightforward. However, it also places the burden of data integrity and conflict management on the user or developer. Without proper discipline, manual handling of conflicts or corrupt files could become problematic. Nevertheless, this tradeoff favors control, transparency, and resilience, especially in environments where trust and simplicity are paramount.

Tradeoffs: When Local-First Gets Trickier

While the disk-as-contract approach offers speed and portability, it also brings challenges. Conflict resolution can get complex in large teams, and ensuring consistency across devices needs careful sync strategies.

For example, if two devices modify the same card offline, merging changes requires clever rules or manual intervention. Data migrations? You’ll edit JSON files directly — not always as smooth as a database schema update.

Plus, trust in local disk integrity matters. Corruption or hardware failure can threaten your data unless you have good backups.

Moreover, as projects scale, managing numerous files and conflicts can become a significant overhead. The simplicity of individual JSON files may turn into a liability if not managed with proper tooling or strict conventions. Developers must weigh the benefits of transparency and portability against the increased complexity of conflict management and data integrity, especially in collaborative or large-scale environments. The tradeoff here is between raw control and operational complexity, which can impact productivity if not carefully handled.

Where Threlmark’s Approach Shines and When It Risks Falling Short

Threlmark’s local-first, disk-based design shines for solo developers, small teams, or anyone needing offline resilience. It fosters transparency, control, and portability, making it perfect for creative workflows or personal project management.

But, for large-scale collaboration or environments needing strict consistency (like enterprise apps), the complexity of sync and conflict resolution can become a headache. The approach works best when you can accept some manual conflict handling or have a good backup plan.

Understanding these limitations helps teams decide whether this architecture aligns with their needs. It’s a powerful approach for certain contexts but may require adjustments or supplementary tools in more complex settings. The key is recognizing that while it offers significant advantages in transparency and resilience, it also demands discipline and awareness of its limitations, especially as projects grow in size and complexity.

Getting Started with Threlmark and Its Architecture

If you want to explore Threlmark’s approach, check out its open-source repo on GitHub. The core idea is simple: organize your data as JSON files in a folder, and let the system read, write, and merge them.

Here’s a quick step-by-step:

1. Download and install Threlmark from its [GitHub repository](https://github.com/MeyerThorsten/threlmark).
2. Create a data folder, set the `THRELMARK_DATA_DIR` env variable.
3. Start editing project files directly — add cards, reorder lanes, link projects.
4. Let Threlmark sync changes when devices reconnect.

It’s a straightforward way to keep your data portable, transparent, and offline-capable.

Frequently Asked Questions

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

It means that the files stored on your disk define everything about your system’s state. The app reads and writes these files directly, making the data transparent, portable, and the ultimate source of truth.

Why choose a local-first design over a traditional cloud setup?

Local-first ensures your work is always accessible, fast, and resilient to network issues. You can work offline, avoid vendor lock-in, and have full control over your data — ideal for creative, remote, or privacy-conscious workflows.

How does Threlmark handle conflicts when multiple devices edit the same data?

It compares timestamps and merge rules, favoring the latest change or flagging conflicts for manual resolution. This keeps data consistent without central servers, relying instead on simple, atomic file operations.

Can I migrate my data easily?

Yes. Since all data lives in plain JSON files, you can back up, move, or sync your entire project folder with basic tools like copy or cloud storage — no special database export needed.

Is this approach good for large teams or enterprise apps?

It works well for small teams or personal use. Large teams face more complex conflicts and sync challenges, so this architecture suits scenarios where manual conflict resolution and transparency are acceptable tradeoffs.

Conclusion

Threlmark’s disk-as-contract approach transforms how we think about data management — making it simple, resilient, and flexible. Your project’s truth lives on your disk, ready to be inspected, backed up, or moved at any moment.

Imagine a future where your tools are just files on your local machine, working smoothly offline and syncing effortlessly when needed. That’s the promise of this design — a quiet revolution in local-first architecture.