Imagine a project management tool that doesn’t rely on a cloud or a database. Instead, everything lives on your disk, in plain JSON files. It sounds simple, but it’s a radical shift from how most apps handle data.

Threlmark’s architecture proves that the disk itself can be the contract—making your data portable, safe, and always available, even offline. Today, you’ll see how this approach turns complexity into clarity and why it might just change how you think about managing work and collaboration. Learn more about Threlmark’s local-first architecture.

Key Takeaways

• Treat the disk as the single source of truth by organizing data in a predictable folder structure of JSON files.
• Use atomic write patterns to prevent corruption and facilitate safe, concurrent updates.
• Store each project item as a separate file to enable conflict-free, granular editing.
• Leverage offline-first design to work seamlessly without internet, syncing changes via file exchange.
• Understand the tradeoffs: this approach excels for small to medium projects but may face challenges at scale.

Why Threlmark’s Disk-Based Design Changes Everything

At the heart of Threlmark’s approach is a simple truth: the files on your disk are the system’s source of truth. There’s no server, no database, just a structured folder of JSON files that tell the story of your projects. Discover more about local-first data management.

For example, every task card, project info, and dependency lives in its own file. When you open your app, it reads these files directly. When you make a change, it writes back atomically. This transparency makes debugging, migration, and collaboration straightforward.

By relying on the disk as the single source of truth, Threlmark reduces the complexity often associated with server-based or database-driven systems. It simplifies data synchronization, as the files themselves contain all necessary information, and makes version control and backups more straightforward. However, this approach also places greater importance on careful file management and conflict resolution, especially as projects grow larger or become more collaborative. The tradeoff is that while this model excels in simplicity and offline resilience, it can face challenges at scale, requiring thoughtful strategies for handling concurrency and large datasets.

How the File Layout Acts as a Contract for Everything

Threlmark organizes its data in a clear, predictable folder structure. At the root, you find a manifest file and dependency graph. Each project has its folder with metadata, lane order, and cards represented as individual JSON files. Explore how folder structures serve as data contracts.

For example, a card like “Finish report” is stored as items/abc123.json. External suggestions, handoffs, and reports go into dedicated folders. This structure isn’t just storage — it’s a contract everyone follows.

Because every artifact is a file you can cat, diff, or grep, debugging and migration become trivial. This transparency means that anyone with access to the folder can understand and modify the data directly, fostering better collaboration and easier troubleshooting. It also simplifies backup and migration processes, as you can move or restore the entire project state by copying a folder. Read more about file-based contracts.

Making File Operations Safe with Atomic Writes and Merging

Writing files might seem risky, but Threlmark uses atomic operations. Each save is a quick rename of a temp file, so crashes leave no half-written data. Learn about atomic file operations in local-first systems.

Updating a card isn’t rewriting the whole list. Instead, each card gets its own file, so multiple tools can edit different cards simultaneously without clashing. When the app reads a folder, it reconciles the current files, fixing any missing or outdated data.

This pattern makes the system robust. For example, if two devices update different cards, the conflict is local, and no data gets overwritten unexpectedly. However, this approach requires careful handling of conflicts and versioning. If two changes occur simultaneously on the same file, a conflict resolution strategy—such as last-write-wins or user prompts—must be implemented. The main tradeoff is that while atomic writes and per-item files greatly reduce corruption and conflicts, they necessitate additional logic to manage concurrent edits effectively, especially in collaborative environments with multiple users or devices.

Why One File Per Item Beats Big JSON Arrays

Many projects store a roadmap as one big JSON array. It’s easy to imagine, but it’s a disaster for concurrency. Threlmark avoids this by giving each task card its own file — items/.json. See how per-item files improve scalability.

This design allows external tools or scripts to edit individual cards without locking the whole list. When the app loads, it self-heals the lane ordering based on existing files. If a card is deleted or added, the lane list updates automatically.

In addition to improving concurrency, this approach significantly enhances the maintainability of the system. Developers and users can modify individual files without risking corruption of the entire dataset, and version control systems can track changes at a granular level. The main tradeoff is that managing hundreds or thousands of small files can become cumbersome if not properly organized or if the filesystem performance degrades. But overall, this per-item approach fosters a more flexible, scalable, and conflict-resistant environment compared to monolithic JSON arrays.

How Offline-First and Sync Make Threlmark Resilient

Threlmark works beautifully offline. Since all data is just files, you can open the app, make changes, and close it — no internet needed. When you’re back online, sync happens smoothly.

Sync isn’t about pushing data to a server. Instead, it’s about exchanging file diffs or copies between devices. If two devices edit the same card, Threlmark’s conflict resolution keeps versions intact, and the user can merge changes.

This design means that users are never blocked by connectivity issues, and data integrity is maintained through simple file exchanges. The tradeoff is that conflict resolution can become complex if multiple edits happen simultaneously on the same file, requiring robust merging strategies. Nonetheless, the offline-first approach ensures continuous productivity and data safety, even in environments with unreliable internet or in remote locations.

Conflict Handling Without a Database — What Really Happens

Conflict resolution is a core challenge in local-first systems. Threlmark’s approach is simple: if two devices change the same card, the last write wins, but the system keeps track of versions.

For example, if you rename a task on your phone and your laptop also edits it, Threlmark merges the changes, keeping both updates and alerting you if needed. It does this by comparing file timestamps and content hashes.

This method avoids complex merge algorithms, relying instead on a straightforward, transparent system that’s easy to understand and troubleshoot. However, this simplicity comes with tradeoffs — in high-collaboration scenarios, conflicts may require user intervention or more sophisticated merging strategies to prevent data loss. The key is that this method provides a clear, understandable conflict resolution process that aligns with the transparency of the file-based system, making it easier to diagnose issues and maintain consistency.

Developer Tips: Debugging and Extending Threlmark’s System

For developers, working with files is like having a live blueprint. To debug, open a JSON file, see its current state, and compare it to your last change. No mysterious APIs or opaque data stores.

If you want to extend Threlmark, just add new files or folders following the existing structure. The app will pick them up on next load. Need to fix a bug? Edit the JSON directly or write a script to automate changes.

This transparency reduces bugs and makes customizations straightforward. Plus, since the data is plain JSON, you can use your favorite tools — editors, VSCode, jq, whatever.

However, developers should be aware of the importance of maintaining the integrity of the folder structure and handling potential conflicts or corruptions proactively. Proper version control practices and validation routines can help ensure stability as the system grows or becomes more complex.

Tradeoffs: When File Storage Might Not Be Enough

While Threlmark’s approach offers simplicity and transparency, it’s not a one-size-fits-all. Large datasets, high concurrency, or real-time collaboration can strain a file-based setup.

For example, if you have thousands of cards updating simultaneously, the system might slow down due to filesystem limitations or increased complexity in conflict resolution. Similarly, complex queries or transactional operations—like aggregating data or performing batch updates—are harder without a dedicated database engine that supports indexing and atomic transactions.

In such cases, hybrid solutions — combining local files with a backend database or server — may be necessary to handle scale and complexity effectively. But for many small to medium projects, this architecture offers an elegant balance of simplicity, resilience, and control.

Getting Started with Threlmark — Your Next Step

Want to see Threlmark in action? Visit their GitHub repository and try it out. It’s a Next.js app that reads and writes JSON files directly from your disk.

Start by cloning the repo, setting the environment variable for your data directory, and experimenting with creating and moving cards. Once you see how straightforward it is, you’ll understand why this design is so powerful.

For more details, check their official website or Thorsten Meyer AI for deep dives into the architecture.

Frequently Asked Questions

What does ‘Disk is the contract’ really mean?

It means the on-disk JSON files are the definitive source of truth for the app. All data, structure, and state are stored directly on your disk, making the system transparent and easy to manage.

How is this different from using a traditional database?

Instead of a server or database, data lives in individual files you can inspect and manipulate directly. This makes the system more resilient offline and easier to back up or migrate.

Why choose JSON files over SQL or NoSQL stores?

JSON is simple, readable, and portable. It requires no special setup or dependencies, and makes debugging and manual editing straightforward.

How does sync work when the app reconnects?

Sync involves exchanging file differences or copies between devices. Changes are merged based on timestamps and hashes, ensuring consistency without a central server.

Is this approach safe or risky?

When implemented with atomic writes and conflict management, this approach is very safe. However, very large datasets or high concurrency might require more robust solutions.

Conclusion

Threlmark’s architecture proves that simple, transparent file-based storage isn’t just nostalgic — it’s powerful. When you treat the disk as the contract, you gain control, portability, and resilience.

Imagine a future where your project data is always accessible, editable, and safe, no matter where you are. That future starts with a single file, a simple idea, and a bold choice.