Imagine a project management tool that doesn’t rely on a cloud server or a database. Instead, it lives entirely on your disk, with every change stored as a simple JSON file. That’s the core idea behind Threlmark’s architecture, where the filesystem becomes the system of record.

This design isn’t just about avoiding servers. You can learn more about local-first architectures. It’s about creating a resilient, portable, and open system that works offline, scales with your needs, and supports external tools without fuss. You’re about to see how a straightforward on-disk layout can power a complex, multi-project workflow—without the usual database overhead.

Key Takeaways

• Treat your disk as the ultimate source of truth by organizing data in a clear, file-based layout.
• Atomic file writes prevent corruption, making your data safer during crashes or interruptions.
• Conflict resolution relies on timestamps and tolerant merging, suitable for small teams or solo workflows.
• External tools and AI agents can participate seamlessly by reading and writing JSON files directly.
• Self-healing boards and reconciliation keep your data consistent, even with concurrent edits.

Why Threlmark’s ‘Disk Is the Contract’ Changes Everything

In most apps, the database is the single source of truth. Threlmark flips that idea. Here, the disk holds your entire data state, making it the ultimate authority. This means every file, from a project’s metadata to individual task cards, is a piece of the truth.

For example, your task cards are stored as items/.json files. When you update one, the app writes that file directly, ensuring consistency. No central server, no special database, just plain JSON files. This approach makes data transparent and portable—backup by copying, sync with any tool, and easy to inspect or modify.

How Local-First Works: Offline, Resilient, and Syncing Seamlessly

Local-first means you can work offline without losing a beat. Threlmark’s architecture stores all data locally, so you can add, update, or move cards even without internet. When connectivity returns, changes sync automatically.

For example, if you’re on a plane, you can reorganize your roadmap. As soon as you land, the system syncs these updates—merging conflicts intelligently. This is made possible because each change touches only a single file, avoiding complex lock systems.

Sync isn’t just about copying files. Threlmark uses a combination of file versioning, timestamps, and conflict resolution—ensuring your data stays consistent across devices.

The File Layout That Powers Everything

The core of Threlmark’s architecture is its disciplined file layout. At the root, you find a manifest (threlmark.json) and dependency graph. Each project has its own folder with metadata, lanes, and a list of item files.

Most importantly, each task card lives in items/ as a separate JSON file. When you change a card, only that file updates. The lane order is stored in board.json, which reconciles itself each time it loads.

Shared cards are stored under shared/items/. When a project archives, its folder moves to archive/, keeping everything readable but out of the active workspace.

Why Using Files Is Safer and More Flexible Than Databases

Many assume databases are necessary for complex data, but Threlmark shows that files can do the job just fine. Using atomic write patterns, each file update is safe from corruption—even if your system crashes mid-write.

For instance, writing to a file involves creating a temporary version, then renaming it atomically. This guarantees that the data is either fully written or untouched—no half-baked states.

Plus, files are easy to back up, migrate, and inspect. You can move them to another device or tool without vendor lock-in, making the system truly portable.

Handling Conflicts and Merging Changes Like a Pro

Conflicts are inevitable when multiple devices edit the same data. You can explore conflict resolution strategies on surveillance and conflict handling. Threlmark handles this with a simple but effective approach: last-writer-wins combined with merge strategies.

For example, if two devices update the same card simultaneously, the system merges changes based on timestamps and known defaults. Unknown fields are preserved, so no data gets lost as formats evolve.

This approach means you can edit on your laptop and phone with confidence—changes merge smoothly without manual intervention.

The Magic of Self-Healing Boards and Incremental Sync

The lane order isn’t stored as a monolithic list. Instead, board.json contains ordered references, and on each load, Threlmark reconciles it with existing items. Missing or mismatched entries get corrected automatically.

Imagine a scenario: you move a card to a new lane on one device. When you sync, the lane list updates itself to reflect the actual items, healing any discrepancies without manual cleanup.

This self-healing keeps your boards accurate and reduces sync conflicts, even with multiple concurrent edits.

How External Tools and AI Agents Play Nice with JSON Files

Threlmark’s file structure invites external tools to participate effortlessly. For more insights, visit Elfys World about innovative integrations. You can script a tool to modify items/ files, and it just works. No APIs to learn, no special permissions needed.

For example, an AI agent can analyze your task files, suggest updates, or even move cards to Done—all by reading and writing files directly. This openness accelerates automation and collaboration.

Plus, the system logs all reports and handoffs in dedicated folders, making it easy for AI tools to track progress and provide feedback.

Tradeoffs: Simplicity vs. Complexity in Sync and Conflict Handling

Using files simplifies many things but shifts complexity elsewhere. Syncing and conflict resolution become the main challenges. Threlmark handles this with versioning, timestamps, and tolerant merging.

For example, instead of locking data, the system relies on atomic file writes and reconciliation. This approach works well for small teams and single-user workflows but needs care as scale grows.

In larger systems, you might need more sophisticated conflict resolution or a hybrid approach. Still, the core idea remains: local-first, disk-as-the-contract simplifies the architecture but demands smart conflict handling.

Real-World Use Cases and Why This Architecture Shines

Think of a solo developer managing multiple projects, or a team working across devices in remote areas. Threlmark’s architecture excels in these scenarios. It’s resilient, portable, and responsive.

For instance, a designer working offline on mood boards can sync updates later, all stored as JSON files. No internet needed. It’s perfect for distributed teams or environments with flaky connections.

In fact, many small teams are adopting local-first designs inspired by Threlmark, especially with tools like [Threlmark](https://threlmark.com) making it easier to implement.

Frequently Asked Questions

What does ‘disk is the contract’ actually mean?

It means that the entire system is built around files stored on disk, where each file is an authoritative piece of data. There’s no central database—files are the system of record, making data portable, transparent, and easy to sync.

Why use JSON files instead of a traditional database?

JSON files are simple, portable, and easy to inspect. They avoid vendor lock-in, simplify backups, and support open collaboration. Plus, with atomic writes, they’re safe from corruption even if your system crashes.

How does syncing work across devices?

Changes are written locally as files, then synced using versioning, timestamps, and conflict resolution. When a device reconnects, it merges updates, ensuring everyone sees the latest, conflict-free data.

Can this system handle large-scale projects or teams?

It’s ideal for small teams or solo workflows. For larger projects, you might need more advanced conflict resolution or hybrid solutions. Still, the core idea of local-first, disk-as-the-contract scales well for many use cases.

What are the biggest risks or downsides?

Sync conflicts and file corruption are potential issues if not handled carefully. Also, managing many files can become complex at scale, and conflict resolution strategies need to be robust for larger teams.

Conclusion

Threlmark’s design shows that the simplest approach—using the disk as the contract—can be powerful. It turns data into a portable, offline-friendly asset that’s easy to inspect, back up, and extend.

Imagine a future where your tools talk directly to your files, and the filesystem becomes your most reliable partner. That’s the promise of disk as the contract. Are you ready to rethink what your data can do?