Imagine a project management tool that doesn’t store data in a database or cloud. Instead, it treats your files on disk as the ultimate record of truth. That’s the core idea behind Threlmark’s local-first architecture. It’s a bold move, but it pays off in transparency, control, and resilience. No lock-in, no hidden layers—just plain JSON files that anyone can read, edit, and sync. If you’ve ever felt frustrated by opaque databases or locked-in platforms, this approach might be the fresh perspective you need. Here’s how it all works and why it matters.

Key Takeaways

• Threlmark’s core idea is that the on-disk file layout *is* the API, making data transparent and easy to inspect or modify.
• Using one file per item prevents race conditions and allows external tools and AI agents to safely read and write data without locks.
• Atomic write techniques and tolerant merging safeguard data integrity even when files are manually edited or corrupted.
• The folder structure acts as a formal contract, enabling seamless interoperability and simple backups or migrations.
• Self-healing mechanisms ensure the project view remains consistent, even with manual or automated changes.

What does ‘disk is the contract’ actually mean?

At its heart, ‘disk is the contract’ means the files on your disk are the definitive source of truth. Think of it like a public ledger, where every change is a new line in a plain text file. The system’s rules, structure, and data all live in those files, making the data transparent and accessible. For example, Threlmark stores each project, card, and dependency as individual JSON files, so you can open, edit, or troubleshoot them directly in your editor.

This approach sidesteps the complexity of traditional databases, which hide data behind layers of abstraction. You can learn more about Disk Is the Contract: Inside Threlmark’s Local-First Architecture for a deeper understanding. Instead, you and your tools read and write files directly, trusting that the files are always correct and up-to-date. This transparency allows for easier debugging, manual intervention, and greater confidence in data integrity. However, it also means that managing consistency becomes a shared responsibility: if files are manually edited or corrupted, it can lead to discrepancies that need resolving. The tradeoff is simplicity and control at the expense of requiring some discipline in handling concurrent edits and conflicts.

Why choose plain JSON files over a database?

JSON files are simple, human-readable, and portable—perfect for a local-first app. Unlike databases, which require complex setup, migration, and locking mechanisms, JSON files let you see and manipulate your data directly. For example, if your project has 50 cards, each one lives in its own file, making it easy to edit, back up, or sync.

This simplicity also means that you avoid vendor lock-in and reduce the risk of data corruption or schema migrations that can be complex in traditional databases. For related insights, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. You can manually edit files to fix issues or inspect data, which is invaluable during debugging or emergencies. However, this approach also shifts some complexity onto the user or developer: managing concurrent edits, resolving conflicts, and ensuring consistency across files require careful handling. The tradeoff favors transparency and flexibility over the robustness and scalability of traditional database systems, making it ideal for small to medium projects that prioritize control and offline capabilities.

How does Threlmark handle multiple devices and conflicts?

Threlmark’s architecture shines in multi-device setups. You can explore similar concepts in Disk Is the Contract: Inside Threlmark’s Local-First Architecture. Each device reads and writes JSON files directly, which means changes are immediately reflected in the file system. When two devices edit the same file independently, conflicts can occur—this is an inherent challenge in distributed systems relying on file synchronization. However, Threlmark is designed to handle these situations gracefully by encouraging conflict-aware workflows. For instance, tools can detect conflicting versions during sync and prompt users to review differences, merge changes manually, or apply conflict resolution strategies.

The implication is that users need to be aware of potential conflicts and manage them consciously. This can be seen as a tradeoff: while it offers offline resilience and avoids complex locking mechanisms, it requires a disciplined workflow to prevent data loss or inconsistency. Automated conflict resolution can be implemented, but it often involves assumptions about how to merge divergent changes, which may not always be perfect. The benefit is a system that supports offline work and multi-device access without reliance on centralized servers, but with the necessity for conflict management strategies.

What role do agents play in this file-centric system?

Agents in Threlmark are automation tools that read and modify files directly. To see how automation integrates with local-first systems, visit Disk Is the Contract: Inside Threlmark’s Local-First Architecture. They can suggest new cards, move items, or mark tasks as done—all by editing the JSON files on disk. For example, an AI agent might scan your backlog, identify high-priority items, and automatically move them into your “Today” lane by updating a file.

This direct file manipulation makes automation transparent and safe. Since files are the source of truth, agents just follow the same rules as your manual edits. They can also participate asynchronously, send reports, or even trigger other tools—all without needing a special API or database layer. This approach ensures that automation remains consistent with manual workflows, reducing the risk of divergence and making it easier to troubleshoot or audit changes since everything is stored in plain files.

How does the folder structure act as a formal contract?

Threlmark’s folder layout isn’t just organization—it’s a formal contract between tools and the system. More details can be found at Disk Is the Contract: Inside Threlmark’s Local-First Architecture. At the root, a manifest file describes overall setup, while each project has its own folder with files for cards, lanes, and dependencies. For example, the `items/` directory contains one JSON file per task, making each piece of work independently accessible.

This structure guarantees that any tool can read or write specific parts of your project without breaking others. It also makes backups, migrations, or manual edits straightforward. By adhering to this folder and file organization, developers and tools can reliably interpret the data format, facilitating seamless interoperability. The tradeoff is that this rigid structure requires discipline in maintaining naming conventions and folder hierarchies, but it ultimately provides a clear, predictable contract that simplifies data management and integration.

What safeguards make file-based data safe and reliable?

Using files might seem risky, but Threlmark employs atomic writes and tolerant merging to keep data safe. For more on data safety practices, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. Atomic writes involve writing to a temporary file first, then renaming it—if something crashes mid-write, the old file remains intact. For example, when saving a card update, the system first writes to `card123.json.tmp`, then swaps it over. This ensures that partial writes do not corrupt existing data, preserving consistency even in the face of crashes or power failures.

Read-merge-write patterns further protect data integrity by carefully merging incoming changes with existing content, respecting the structure and avoiding overwriting important information. Tolerant merging allows the system to handle unknown or extra fields gracefully, supporting schema evolution without breaking compatibility. These safeguards collectively provide a resilient environment that prioritizes data safety while maintaining the flexibility of plain files, although they may introduce some complexity in conflict resolution and version management.

How does Threlmark’s self-healing board work?

The board in Threlmark is stored as a separate JSON file listing item IDs in order. It self-heals on read—if a card exists in `items/` but isn’t listed on the board, it’s added automatically. For example, if a new task is created outside the board file, it appears in the next read cycle, keeping the view consistent.

This automatic reconciliation prevents desynchronization and manual cleanup, making the system more robust. It’s akin to a GPS that recalibrates itself—if files are manually edited or if some data is missing, the system adjusts the view to reflect the actual state, reducing errors and inconsistencies. This approach simplifies manual maintenance and enhances reliability, but it also requires that the self-healing logic is carefully implemented to avoid unintended side effects, such as inadvertently displaying outdated or irrelevant items.

What are the main benefits of this file-based approach?

• Transparency: you can see and edit data directly.
• Portability: move files anywhere, no lock-in.
• Resilience: offline work and manual recovery are straightforward.
• Interoperability: any language or tool can join the party.
• Control: no hidden layers—your data lives in plain sight.

Frequently Asked Questions

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

It means the files on your disk are the definitive source of truth. Every change, every state, lives in plain JSON files that any tool can read or write, making your data transparent and portable.

Why use JSON files instead of a database?

JSON files are simple, human-readable, and portable. They make it easy to see what’s happening, manually fix issues, and avoid vendor lock-in, all while supporting offline workflows.

How does sync and conflict resolution work?

Each device reads and writes files independently. Conflicts can be merged or manually reviewed, making the system resilient and offline-friendly. Changes propagate naturally via file sync tools.

Can agents modify the source data directly?

Yes. Agents in Threlmark edit the JSON files directly, enabling automation that’s transparent and safe, since the files are the source of truth.

Is this suitable for team collaboration or only solo work?

It works well for both. The file-based approach simplifies sharing, syncing, and conflict resolution, making it ideal for multi-device and team environments as long as sync is managed carefully.

Conclusion

Thinking of your project data as files on disk turns complexity into clarity. Instead of hiding behind databases, you gain transparency, control, and resilience. That’s the real power of ‘disk is the contract’—a simple idea that rewires how we build and automate. Ready to give it a try? Your files are waiting.