Imagine managing your entire project roadmap without relying on a cloud database or a web server. Instead, every piece of data lives in plain JSON files on your disk, accessible and editable directly. That’s the core of Threlmark’s local-first architecture. It’s a bold move—one that shifts control back to you, the user, and away from centralized systems. In this article, you’ll see how this design empowers your workflows, simplifies collaboration, and paves the way for more autonomous AI agents to work seamlessly with your data.

Key Takeaways

• Using plain JSON files as the system of record makes project data fully portable, inspectable, and easy to back up or migrate.
• Atomic file writes and self-healing reads ensure data safety and consistency without locks or complex synchronization.
• A filesystem-based architecture prioritizes local control, offline access, and privacy, suitable for solo or small-team workflows.
• Tradeoffs include scalability challenges and the absence of advanced database features, which are manageable for smaller projects.
• Threlmark’s design empowers AI agents to interact directly with project data, enabling automation without a server or cloud.

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

At its core, ‘disk is the contract’ means all project data lives in files on your local disk. There’s no central server or database holding the record. When you or an external tool access a project, it reads the JSON files directly. This simple, transparent approach makes everything easy to inspect, back up, and move around.

For example, your roadmap cards are stored as individual JSON files in a folder, each representing a single task. Changing a card means editing its file. No API calls, no network, just plain file operations that everyone can understand and verify.

Why does Threlmark prefer JSON files over a database?

JSON files are human-readable, making it easy to see exactly what’s stored. Unlike a database, they require no special tools or schemas. You can open, edit, or migrate them with basic commands or scripts.

For instance, if you want to review your project’s tasks, a quick cat items/abc123.json shows everything. Plus, JSON’s flexibility allows the system to grow without breaking existing tools—unknown fields are preserved, and the files remain compatible.

How does Threlmark handle concurrency and conflicts?

Threlmark uses atomic file writes—write to a temp file, then rename it. This guarantees that updates are either fully written or not at all, avoiding partial corruption.

When multiple tools or agents modify files simultaneously, each change is isolated in its own file. The system self-heals by reconciling the folder’s contents on each read, ensuring consistency without locks or complicated synchronization.

For example, if two agents update different cards at once, each writes its own JSON file atomically. The next read merges everything seamlessly, avoiding race conditions.

What are the real benefits of a local-first, filesystem-based system?

Local-first means your data remains accessible even when offline. No need to sync with a remote server constantly. You have full control and immediate access to your project state.

This approach also enhances privacy—sensitive info stays on your device unless you choose to sync it elsewhere. Plus, it simplifies backup and migration: copy a folder or use standard tools like Dropbox or git.

For instance, a developer working on a plane can continue editing their roadmap without interruption, then sync changes later.

Beyond convenience, this architecture fosters a deeper understanding of your data. Since everything is stored in plain files, you can learn exactly how your data is structured, troubleshoot issues directly, and even customize workflows without vendor lock-in. This transparency means you can see every change and understand its implications, which leads to more secure and predictable project management. However, it also requires users to adopt disciplined data management practices—manual oversight becomes more important to prevent issues like duplicate or inconsistent files. Trusting plain files as the source of truth emphasizes the importance of good organizational habits, but it offers the benefit of complete control and insight into your data lifecycle, which is crucial in sensitive or autonomous environments.

What are the tradeoffs of a filesystem-only approach?

Relying solely on files means you lose some features built into traditional databases—like built-in conflict resolution, complex querying, or real-time collaboration. Handling large datasets can become cumbersome, as searching through thousands of files can slow down operations and make management more manual.

For example, if your project grows to thousands of cards, searching and managing files might slow down compared to a dedicated database optimized for large-scale data operations. Additionally, without a database’s schema enforcement, it’s easier for data inconsistencies or corruptions to slip in, especially if manual edits are not carefully managed.

However, for many workflows, especially solo or small-team projects, this tradeoff is acceptable given the benefits of control and simplicity. It encourages disciplined data management, where users are responsible for ensuring consistency and organization. While it may require more manual effort or custom tooling for scaling, the tradeoff favors agility and transparency over complexity, which aligns well with many small-scale or autonomous workflows. Recognizing these limitations helps users design their workflows proactively, using scripts or checks to maintain data integrity and performance as their datasets expand, and understanding that the simplicity of the filesystem approach is a deliberate tradeoff for flexibility and control.

How does Threlmark keep data safe and consistent?

Atomic file writes are the backbone of safety—preventing corruption during crashes or interruptions. The system also uses read-merge patterns, which preserve unknown fields and allow forward compatibility.

For example, if a new version adds a field, older tools still read the JSON without breaking. When saving, updates bump timestamps and preserve existing metadata, ensuring data integrity over time. This approach minimizes risk, but it also requires careful implementation—any lapse in atomicity could lead to data corruption, especially during unexpected shutdowns. Therefore, using reliable filesystem operations and thorough testing is crucial to maintain this safety net. Moreover, the system’s reliance on simple, atomic operations means that implementing proper safeguards—such as verifying file integrity after writes—is essential to prevent subtle corruption or data loss, especially in multi-user or unstable environments. This disciplined approach to data safety emphasizes the importance of robust tooling and best practices, ensuring that the system remains resilient even under adverse conditions.

What kinds of apps are best suited to this architecture?

Apps that benefit from local control, portability, and simplicity shine here. Solo project managers, small teams, or automation tools with agents thrive with Threlmark’s design.

For example, a developer running multiple AI agents on their laptop to manage tasks, code, and documentation can do so efficiently without worrying about server downtime or data lock-in.

It’s especially powerful when your workflow involves frequent offline work or needs seamless integration with existing file-based tools. This approach encourages a modular, flexible, and transparent ecosystem where individual components can evolve independently, making it ideal for innovative, autonomous, or highly customized workflows. The key is that these applications leverage the filesystem as their primary interface, which fosters a more natural, intuitive interaction with data that aligns with human workflows and reduces dependencies on complex infrastructure.

What about scaling and future risks?

As data grows, managing large numbers of files can slow things down. Search and querying become less efficient without a dedicated database engine. This can lead to longer load times and increased manual effort to keep data organized.

Risks include inconsistent states if atomic operations aren’t carefully implemented or if external tools don’t follow the discipline. For example, unsynchronized manual edits or improper scripting can lead to corrupt or incomplete data states, especially in multi-user environments. Additionally, the absence of advanced conflict resolution features means that conflicts must be managed externally or through disciplined workflows, which can be error-prone.

However, with proper organization, disciplined workflows, and tooling—such as scripts that verify file integrity—these issues can be mitigated. For small to medium projects, the simplicity and transparency often outweigh these risks. Planning for scalability involves establishing conventions, automating checks, and possibly integrating lightweight indexing tools to maintain performance as data volume increases. Recognizing these potential challenges ensures you can adapt your workflow proactively, using tools and best practices to sustain data integrity and performance over time.

Frequently Asked Questions

What does ‘disk is the contract’ mean in simple terms?

It means all your project data lives on your local disk in plain JSON files, and these files are the definitive source of truth. No central server or database holds the final record—your files do.

Why choose JSON files instead of a traditional database?

JSON files are human-readable, easy to edit, and don’t require special setup. They make your data transparent, portable, and flexible, especially for small or solo projects.

How does Threlmark handle multiple tools editing files at once?

It uses atomic writes—write to a temp file then rename—so updates either fully succeed or not at all. The system also reconciles the folder’s contents on each read, keeping everything consistent.

Is this approach good for large-scale projects?

It works well for small to medium projects but can face performance issues with thousands of files. For bigger datasets, a dedicated database might be better, but for many workflows, this is enough.

Can I use external tools or AI agents with this setup?

Yes. Since data is in plain files, agents and tools can read and write directly, making automation seamless without needing special APIs or servers.

Conclusion

Treating the disk as the contract turns your project data into a transparent, portable, and resilient asset. It’s a deliberate shift that puts control back in your hands—no middlemen, no lock-in, just plain files. If you value simplicity, privacy, and local-first workflows, this approach offers a compelling path forward. Your next project could be built on nothing more than a folder and a few JSON files—trust the disk, and watch your tools work better.