Imagine a project management system that never relies on a cloud server or a proprietary database. Instead, it lives right on your disk—simple, transparent, and easy to back up. That’s what Threlmark does. It turns the idea of data storage upside down, making your project data a set of plain files that anyone can read, modify, and sync.

If you’ve ever wrestled with database lock-ins or lost work due to server crashes, you’ll see the appeal. We’re about to explore how treating disk as the contract unlocks a new level of simplicity, safety, and flexibility—especially for anyone who loves control, transparency, and offline work.

Key Takeaways

• Treat disk files as the single source of truth—every change is a human-readable JSON file.
• Use atomic writes to prevent corruption during crashes or concurrent edits.
• Design your system with one file per item to keep data manageable and conflict-free.
• Leverage the self-healing nature of reading from the file system to maintain consistency.
• Embrace local-first principles for offline work, portability, and user control.

Why Threlmark Swears by the Disk as Its Single Source of Truth

Disk as the contract means every piece of data is a human-readable file on your filesystem. No hidden layers, no opaque databases. This approach makes the data transparent, portable, and safe—your files are the real record of your project. Disk is the contract.

For example, Threlmark stores each roadmap card in its own JSON file within an “items” folder. When you open that folder, you see exactly what’s in your project—no secret database structure. This makes it easy to back up, move, or sync your data with tools like Dropbox or Git.

According to Disk is the contract, this file-based approach aligns perfectly with the local-first movement. It offers resilience against network issues, enables offline workflows, and reduces lock-in risks. The data’s integrity relies on simple file operations—like renaming temp files—so even a crash during a save won’t corrupt your data.

Deeply, this approach shifts the developer and user perspective: instead of managing complex database schemas and migrations, you focus on the integrity and consistency of individual files. It simplifies debugging and enhances trust because you can inspect, modify, and version control the raw data directly. However, this also means that managing concurrent edits and schema evolution requires careful patterns—atomic operations and tolerant merging—to prevent conflicts and data loss. The tradeoff is that while you gain transparency and control, you need to adopt disciplined workflows and understand the implications of file-based concurrency.

How the On-Disk Layout Powers Your Workflow and AI Integration

Threlmark’s directory structure is more than just a file hierarchy; it’s a formal contract. At the root, a “threlmark.json” manifest and a “links.json” graph define your projects and dependencies. Each project has its own folder with files like “project.json,” “board.json,” and individual item files in “items/”.

For example, when an AI agent suggests a new task, it drops a JSON file into “suggestions/”. The system reads, validates, and merges this suggestion with existing data—no database needed. The same goes for reports, handoffs, and status updates. All are plain files, so any tool or agent can participate.

This file layout acts as a formal contract that supports AI workflows, external tool integrations, and manual edits. Disk is the contract. By defining clear locations and formats for each piece of data, it ensures interoperability and predictability. Yet, this structure also implies that the system must handle concurrent modifications gracefully—using techniques like file locking, versioning, or tolerant merging—to prevent conflicts. The tradeoff is that while the architecture is transparent and flexible, it requires disciplined coordination to avoid data corruption or inconsistency when multiple tools interact simultaneously.

Making Files Safe: Atomic Writes and Tolerant Merging

Using files for data storage sounds risky—what if two apps edit the same file at once? Threlmark solves this with simple but effective patterns. It writes to a temp file first, then renames it atomically. This guarantees that partial writes never corrupt data.

For example, updating a task involves reading the current JSON, merging in new info, and writing it back atomically. If your editor crashes midway, the original file stays intact. Plus, the system preserves unknown fields, so older tools won’t wipe out new data.

Research from Disk is the contract confirms that atomic file operations are key to safe, distributed file-based systems. Threlmark’s approach ensures data integrity even in complex, multi-process environments.

Deeply, atomic writes are crucial because they prevent the classic problem of partial or corrupted files that can occur during crashes or concurrent modifications. They enable a resilient workflow where data consistency is maintained without locking entire files or relying on complex transactions. However, they also mean that developers must implement these patterns consistently; neglecting atomicity can lead to subtle bugs. The tradeoff is that atomic operations are simple but require discipline and careful coding to ensure the system remains reliable under all conditions.

The Self-Healing, One-File-Per-Item Design That Keeps Everything in Sync

Instead of a giant JSON array, Threlmark uses one file per item. Each card lives in “items/” with a unique ID. When you open the board, it reads all item files and reconciles the lane order dynamically. Missing files mean the card was deleted; new files mean new tasks.

Imagine you drag a card to a different lane. Threlmark updates “board.json” with the new order, but the real work happens in individual item files. If an external tool deletes a card’s file, it disappears from the view on next read. This design keeps everything consistent, even when multiple tools or agents are involved.

This approach mirrors how Git manages individual files—small changes are easy to track, conflicts are minimized, and the system heals itself on every read. It allows for flexible, decentralized editing while maintaining a consistent view of the project state. The tradeoff is that it requires careful management of file IDs and update processes to prevent orphaned or inconsistent data, but it offers high granularity and robustness in multi-tool environments.

Why Local-First and File-Based Systems Are Game Changers for Your Projects

Local-first systems like Threlmark excel at offline work, fast iteration, and data portability. When your data lives as plain files, you can work anywhere—on a plane, in a basement, or abroad—and sync when you’re back online.

For instance, you could start a project on your laptop, then move the entire folder to another computer or share it with a collaborator. No server needed. This simplicity reduces complexity and opens up new workflows.

Research from [3] highlights that local-first apps improve resilience, user control, and privacy. Threlmark’s design embodies these advantages, making project management more adaptable and portable than ever.

Deeply, this approach also means that users and teams must understand the importance of manual syncs and conflict resolution—since there’s no central authority to enforce consistency. While this empowers users with control and flexibility, it also requires discipline and awareness of potential conflicts. The tradeoff is that local-first systems offer unmatched flexibility and resilience but shift some responsibility onto the user or integrator to manage synchronization and conflicts effectively.

Tradeoffs: What You Trade for Simplicity and Portability

Of course, this approach isn’t perfect. Handling conflicts, schema changes, and synchronization can get tricky. Files are simple, but they require discipline. Threlmark relies on strict patterns: atomic writes, tolerant merging, and self-healing reads.

For example, if two agents modify the same card simultaneously, the last write wins. Conflict resolution isn’t automatic; it depends on your workflow. Schema evolution is handled by preserving unknown fields, but you must plan for breaking changes.

Deeply, this means that while file-based systems are more transparent and flexible, they also introduce complexity in conflict management and schema evolution. You must design your system with clear rules—like versioning, manual merges, or conflict markers—and understand that some conflicts may require user intervention. The tradeoff is that you gain control and simplicity at the cost of extra discipline and oversight, especially as your system scales or evolves.

Getting Practical: How to Build Your Own Disk-First Project Tool

Thinking of building your own local-first tool? Start simple. Use a folder structure like Threlmark’s: one file per item, separate metadata, and a manifest at the root.

Follow these steps:

1. Design your directory layout—where each piece of data lives.
2. Implement atomic save functions—write to a temp file, then move.
3. Read files into your app, merge changes, and reconcile state on every load.
4. Handle conflicts by versioning or last-write-wins, and preserve unknown fields for future-proofing.
5. Test offline scenarios—remove network dependencies, and see if your system still works.

Tools like [5] can help you get started with minimal fuss. Embracing these patterns means your system will be more resilient, flexible, and open.

Frequently Asked Questions

What does ‘disk is the contract’ actually mean?

It means that all your project data is stored in plain files on your disk, and these files define the true state of your project. The app and tools read and write directly to these files, making everything transparent and portable.

Is Threlmark really completely database-free?

Yes, Threlmark relies entirely on JSON files stored on disk. There’s no external database or server involved—just files that any tool can access and modify, making it truly local-first.

How do files stay consistent when multiple tools edit them?

Threlmark uses atomic writes—saving files via a temporary file and renaming them atomically. This prevents corruption. It also reads and merges files carefully, preserving unknown fields for future compatibility.

How does syncing work in this system?

Syncing involves copying the entire folder structure—like Dropbox or Git—since all data is stored as files. Changes are merged based on file updates, and conflicts are resolved through last-write-wins or manual intervention.

What about conflicts or schema changes?

Conflicts can be managed with versioning strategies or manual merges. Schema evolution is handled by preserving unknown fields, so older tools won’t accidentally erase new data. Careful planning helps keep everything consistent.

Conclusion

When your data lives on disk, you gain a new level of control and resilience. It’s a surprisingly simple shift—no need for complex databases or servers. Instead, you get a system that’s transparent, portable, and ready for AI integration.

Imagine your project data as a set of plain files, always accessible, always safe. That’s the power of treating disk as the contract. Your next project tool could look like this—start small, think simple, and watch it grow.