Imagine a project management tool that works perfectly offline, is easy to back up, and can be hacked apart and rebuilt with a simple text editor. That’s the promise of Threlmark’s unique approach. Instead of a traditional database or cloud backend, it treats your disk as the contract—where your data lives and breathes.

This isn’t just a cool trick. It’s a radical shift. By making the filesystem the foundation, Threlmark sidesteps many headaches of modern cloud apps—lock-in, complex sync conflicts, and opaque data formats. Instead, it offers a transparent, resilient, and portable way to manage your work. This article explores how this architecture works, why it matters, and what it means for your workflows.

Key Takeaways

• Treat your disk as the single source of truth—your ‘contract’—by storing data in human-readable JSON files.
• Atomic file writes and tolerant read-merge cycles keep data safe and forward-compatible, even during crashes or schema changes.
• One file per item prevents race conditions and makes external editing, backups, and recovery straightforward.
• The architecture naturally supports offline work and simple sync via file copying, ideal for small teams or solo projects.
• While simple and resilient, this approach works best for moderate datasets and collaborative scenarios where real-time updates aren’t critical.

What Does ‘Disk Is the Contract’ Really Mean?

At its core, ‘disk is the contract’ means your data’s authority lives on your machine’s filesystem. Instead of a server or cloud database dictating what’s true, the files themselves are the source of truth. When you open Threlmark, it reads these JSON files directly, and any external tool can do the same.

For example, a card in your project is just a JSON file under items/. If you edit that file, the app immediately sees the change. This simple, transparent approach eliminates layers of abstraction—no ORM, no complicated sync protocols. It’s like writing on a whiteboard, then having your app read that whiteboard directly. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

How Threlmark Keeps Data Safe and Reliable Using Files

Using files might sound risky. What if the disk writes get interrupted? Threlmark handles this with two smart techniques: atomic writes and tolerant read-merge cycles.

Atomic writes mean each change is first saved to a temporary file, then renamed over the original. If your computer crashes during a save, the old file remains intact. It’s like slipping a new page into a binder—nothing gets lost or corrupted.

For example, updating a task card involves writing a new JSON file with a unique temp name, then replacing the old one in one atomic step. This guarantees no half-finished data.

Read-merge means the system reads the current file, updates only what’s needed, and preserves unknown fields. This makes future-proofing easy—new versions can add fields without breaking older tools.

Why JSON Files Over a Database? Real-World Benefits

Choosing JSON files for storage isn’t just about simplicity. It offers tangible advantages, especially for small teams or solo workflows. JSON is human-readable, so you can peek inside your data with a text editor, making debugging straightforward.

It also means no vendor lock-in. You can back up your entire project by copying files or sync folders with Dropbox or Syncthing—no special connectors needed. Plus, the format is flexible enough to evolve without breaking compatibility. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

For instance, when Threlmark updates its data schema, it preserves old data intact, and tools can ignore unknown fields, making upgrades smooth.

One File Per Item: How It Handles Concurrency and Recovery

Imagine trying to edit a giant spreadsheet—everyone’s racing to change the same cell. Threlmark sidesteps this chaos by giving each card its own JSON file. This means multiple tools can edit different cards simultaneously without conflict.

When the app reads the list of cards, it dynamically checks the items/ folder to see what’s there. If a file is missing or corrupted, the system just skips it or shows a warning. This makes recovery easy—just delete or restore the file. smartcr.org auto-blogging.com

For example, if two external tools update different cards, both changes stick because they’re separate files. No need for complex locking or coordination.

The Self-Healing Board and Lane Management

Threlmark’s board isn’t just a static list. It’s a self-healing system that compares the lane order against actual items every time you load it. If a card gets moved or deleted, the board updates itself.

Imagine a kanban where a card accidentally gets dragged out of a lane. When you refresh, that gap closes, and the lane’s order restores based on the actual files present.

This approach keeps your workflow consistent without manual cleanup, even if external tools or scripts mess with your files.

Sync, Collaboration, and Offline Resilience

Threlmark’s architecture naturally supports offline work. Because data lives on your disk, you can keep editing, adding, or moving cards without the internet. When you’re back online, syncing is just copying files between devices.

Conflicts are rare because each file is atomic. But when overlaps happen—say, two devices edit the same card—Threlmark can resolve conflicts by timestamp or user choice. It’s a simple, reliable model that scales from solo projects to small teams.

For example, syncing a project via Dropbox ensures your team’s updates propagate smoothly, and offline edits stay intact.

Comparing Threlmark’s Approach to Traditional Apps

What This Means for Your Workflow and Data Control

Using disk as the contract puts you in the driver’s seat. You back up by copying files. You migrate data by moving folders. Your data is transparent and portable.

For example, if you want to switch from Threlmark to another tool, just point it at the same JSON files. No APIs, no vendor lock-in, no cloud dependency.

This approach also boosts resilience: if your app crashes or your disk gets corrupted, you can recover by restoring files—no complex recovery procedures needed.

What Are the Tradeoffs? When This Architecture Might Not Fit

This design isn’t perfect for every case. Large datasets can slow down performance, since JSON parsing gets heavier with size. Schema evolution needs careful planning. And, if your team needs real-time collaboration at scale, a server-based system might be better.

For example, a massive project with thousands of cards might see slow load times. Or, a multi-user real-time editing environment might require a more traditional database approach.

Frequently Asked Questions

How does sync work if the disk is the source of truth?

Syncing is as simple as copying files between devices using tools like Dropbox or Syncthing. Because each file is atomic, conflicts are minimized, and you can resolve them manually or via timestamps.

What happens if two devices edit the same card at the same time?

Threlmark resolves these conflicts by timestamp, with the latest change winning. For more complex scenarios, manual review or conflict markers can be used, but in general, the system favors simplicity and safety.

Why choose JSON over a traditional database?

JSON offers transparency, portability, and simplicity. You can directly read, edit, or back up your data without vendor lock-in. It’s ideal for small to medium projects that value control and resilience.

Is this architecture suitable for large-scale or real-time collaboration?

Not necessarily. For projects with thousands of items or those requiring instant multi-user edits, a server or CRDT-based system might be more appropriate. But for personal, small team, or offline workflows, this model shines.

Conclusion

Choosing to make your disk the contract rewires how you think about data. It’s no longer just storage—it becomes the entire interface, the backup, and the collaboration layer.

If you want control, resilience, and simplicity in your tools, this architecture offers a compelling blueprint. Your files are more than just data—they’re your project’s backbone. Imagine the possibilities when your work is just a folder away from being portable, editable, and unstoppable.