Imagine a project management tool that works perfectly offline, needs no server, and everyone can peek into its data directly on disk. That’s the bold promise of Threlmark’s approach. It’s a different kind of architecture—one that flips the usual cloud-first model on its head.

Instead of a database sitting in a server, Threlmark uses plain JSON files living on your disk. This simple, yet powerful idea—’disk is the contract’—shapes everything from concurrency to collaboration. Today, I’ll walk you through how this design works, why it’s so effective, and what it means for your own projects.

Key Takeaways

• Treat your disk as the ultimate source of truth by storing data in plain JSON files. This simplifies backup, migration, and interoperability.
• Design your system so each item is a separate file, enabling atomic updates and reducing race conditions in collaborative workflows.
• Leverage self-healing structures that automatically reconcile inconsistencies, maintaining data integrity without manual intervention.
• Use file-based architecture for offline-first workflows, especially for small teams or solo projects that value transparency and portability.
• Be mindful of scalability and conflict resolution limitations; this approach works best in controlled, small-to-medium environments.

What ‘Disk Is the Contract’ Really Means For Your Data

At its core, ‘disk is the contract’ means your data lives in plain files on your computer. No middleman, no cloud service. When you open Threlmark, you’re directly reading and writing these JSON files, which serve as the ultimate source of truth.

It’s like having your project roadmap written in a notebook—accessible, editable, and portable. If you copy that notebook or back it up, you’ve got your entire project history. No database, no server dependency. This approach makes your data transparent and easy to manage.

Why Plain Files and JSON Make Life Easier

Plain files, especially JSON, are incredibly attractive because they’re human-readable and easy to edit. You can open them in any text editor, see exactly what’s inside, and even tweak them manually if needed.

For example, Threlmark keeps each project card as a separate JSON file in the items/ folder. Want to add a priority? Change a status? Just edit that one file. No complicated migrations or schema updates—just straightforward files that grow with your needs.

Plus, JSON’s structure is flexible. You can add new fields without breaking old tools—think of it like adding new pages to a notebook without ruining the old notes.

How Local-First Design Changes Your Workflow

Using Threlmark feels different from traditional cloud apps. You can work offline, immediately see your changes, and trust that your local files are the real record. When you reconnect, syncing happens seamlessly.

Imagine working on a plane, with no internet, and still updating your roadmap. When you land, Threlmark syncs with your other devices, merging changes—conflicts are handled gracefully because each file is atomic.

This approach reduces the cognitive load: no loading screens, no waiting for server responses. Your data is always just a file away.

Sync, Conflicts, and How Files Keep It Simple

Syncing in a file-based system is surprisingly straightforward. Each item gets its own file, so updates are atomic. When two devices edit the same card, Threlmark uses simple rules—last write wins or manual conflict resolution—to keep things consistent.

For example, if two laptops update the same task, the last one to save overwrites the other. But because each change is just a file write, conflicts are easy to spot and fix.

This simplicity contrasts sharply with complex databases that need elaborate conflict resolution strategies. Here, transparency and atomic operations make everything safer and more predictable.

The Power of Self-Healing Boards and Data Integrity

Threlmark’s board structure self-heals—meaning it constantly checks itself against the actual files. If a card is missing from the lane order but exists in items/, it reappears. This keeps your project view consistent without manual cleanup.

For example, if you accidentally delete a lane or a card, the system automatically detects and restores it on the next read, preserving data integrity.

This design reduces errors and keeps your project data trustworthy, even if you edit files outside the app or encounter interruptions.

Interoperability and External Tools: Making Files Play Nice

Because the data lives as plain files, any tool can join the party. Want to automate task creation? Just write a script that adds a JSON file. Need to visualize dependencies? Read the JSON and generate a graph. Learn more about practical knowledge and systems thinking.

Threlmark’s design invites collaboration from outside developers. They can peek, modify, or extend the system without a custom API or SDK.

For instance, an external AI tool could suggest new cards by creating JSON files in the suggestions/ folder, and Threlmark picks them up automatically.

Operational Tradeoffs: When Files Get Tricky

While simple and transparent, file-based systems aren’t perfect. Handling conflicts across devices can get messy if many people edit the same file simultaneously. Discover more about local-first architectures.

Schema changes require careful migration—adding new fields or changing structure can break older tools if not handled gracefully.

And as projects grow, managing thousands of files might slow down your system. But for many small to medium teams, these tradeoffs are manageable and worth the benefits.

Use Cases Where Threlmark Shines Bright

Threlmark excels in scenarios where offline access, transparency, and portability matter. Solo developers, small teams, or projects that need easy backups find it ideal. Explore sustainable living practices.

Imagine a remote software team working in the woods, disconnected from the internet. They can still update their project roadmap, then sync once connected. Threlmark keeps things simple and reliable.

It’s perfect for personal projects, research workflows, or any environment where control over data beats reliance on cloud services.

Where This Approach Might Fail You

If your team needs real-time collaboration across many users, a file-based system can become a headache. Conflicts multiply, and managing schema evolution gets complicated. Learn about the limitations of local-first systems.

Large-scale projects with hundreds or thousands of files may slow down, and conflict resolution might require custom tools or manual intervention.

In those cases, a database-backed system with server-side logic might be a better fit. Threlmark’s strength lies in simplicity, not scale.

Comparison: Threlmark vs. Traditional Local-First Tools

Feature	Threlmark	Database-Backed Systems
Data Storage	Plain JSON files on disk	SQL/NoSQL databases
Offline Support	Excellent — data is local
Sync Conflicts	Simple, file-based rules
Setup Complexity	Minimal — just files and folders
Scalability	Limited — best for small/medium
Interoperability	High — any tool can read/write files

Frequently Asked Questions

What does ‘Disk Is the Contract’ really mean in practice?

It means your app’s data lives directly on your disk as plain files, especially JSON. This makes your data transparent, portable, and easy to manage without relying on a server or database.

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

It uses simple rules like last-writer-wins and atomic file operations. Conflicts are visible and easy to resolve because each change is just a file update.

Can this system support team collaboration across many devices?

Yes, but with caveats. It works best for small teams or solo projects. Large, highly collaborative environments may face conflict management challenges and slower performance.

How do I migrate schema or add new features?

You need to update your files carefully, often adding new fields or formats. Many tools handle this gracefully by preserving unknown keys, making schema evolution manageable.

Is this approach suitable for large-scale projects?

For very big projects or many concurrent users, a database-backed system might be better. File-based systems excel in simplicity and offline work, not raw scale.

Conclusion

Threlmark’s ‘disk is the contract’ architecture proves that simplicity can power robust, offline-capable tools. By making files the central source of truth, you gain transparency, portability, and resilience.

For your next project, ask: can I treat my disk as the ultimate record? If so, you might just find that less truly is more.