Imagine working on your project without ever worrying about losing data, waiting for slow servers, or juggling multiple apps. Threlmark’s secret? It treats your disk as the contract—your source of truth. This simple shift rewires the entire system, making everything faster, safer, and more flexible.

Instead of a central database, everything lives as files on your device. That means your data is always accessible, even offline. And syncing happens in the background, quietly updating your other devices when connected. This isn’t just a tech trick; it’s a new way to think about data, collaboration, and control.

Key Takeaways

• Treat your disk as the contract—every file acts as the single source of truth.
• Use one file per item to enable collision-free, atomic updates, even offline.
• Design your data layout to be inspectable, portable, and interoperable—no lock-in.
• Implement safety with atomic writes and tolerant merging to prevent corruption and ensure forward compatibility.
• Leverage self-healing boards to keep workflows consistent without manual cleanup.

Why Threlmark’s Disk-Based System Changes Everything

Threlmark’s core idea is straightforward but revolutionary: the disk isn’t just storage—it’s the contract. This means every file, from a project’s metadata to individual task cards, acts as the definitive record of your work. No server, no cloud, just files that anyone can read or write.

This approach makes your data portable and resilient. You can back it up with simple copy commands, sync it with tools like Dropbox or Syncthing, or move it entirely without losing a thing. It’s a different mindset—one that puts control back into your hands.

For example, if you accidentally delete a file or want to review your project history, just open the folder. Everything is inspectable, changelog-ready, and compatible with any tool that understands JSON. That transparency and simplicity are rare in modern apps.

How Threlmark’s File Layout Acts as a Contract

The layout isn’t just a directory structure—it’s a formal agreement about how data is organized. At the top level, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project lives in its own folder, with files for metadata, boards, and individual cards.

Every task or card is a separate JSON file in the `items/` folder. When you update a card, you write a new file and atomically replace the old one. This means no racing or locking—just simple, reliable file swaps.

External tools or AI agents can participate by reading and writing these files, trusting that the structure remains consistent. It’s a clear contract everyone can follow, no matter what language or tool they use. Learn more about local-first architecture.

Making File-Based Data Safe and Reliable

Handling files might sound risky, but Threlmark’s approach makes it robust. Every write is atomic—files are first written to a temporary file, then renamed. This prevents corruption if your app crashes mid-save.

When updating, the system reads the current file, merges changes, and writes back atomically. It also preserves unknown fields, so future upgrades don’t break old data. This approach keeps your data safe and forward-compatible.

Imagine editing a task on your laptop and then switching to your phone. The changes sync seamlessly, because both devices read and write the same files, honoring the contract of the layout.

Why One File Per Item Beats Large JSON Lists

Many projects keep all tasks in one big JSON file, but that’s a headache for concurrency. Threlmark solves this with one file per item. Each card gets its own JSON file, so editing a task doesn’t risk overwriting others.

This makes updates atomic and collision-free. You can have multiple tools or devices changing different cards at the same time without conflicts. Plus, if a device crashes or loses power, only one small file is impacted.

For example, you’re working on a sprint plan across two devices. Editing a card on your laptop and another on your tablet won’t step on each other’s toes. The system just updates the relevant files, maintaining a clean, reliable record.

How the Board Self-Heals and Keeps Your Workflow Smooth

The lane order isn’t stored in a big list but in a separate `board.json` file. Every time you view or update the board, it cross-checks the actual items and fixes any inconsistencies.

If a card is deleted or misplaced, the board dynamically heals itself—no manual fixes needed. This keeps your workflow consistent, even if external tools modify files directly.

Imagine dragging a card from ‘In Progress’ to ‘Done’. The system updates the `board.json`, but if a card gets lost or renamed, it automatically adjusts on the next read. That’s a self-healing design in action.

Sync and Collaboration Without Strangling Your Offline Speed

Threlmark’s design makes sync simple and fast. Changes are local and immediate—no waiting for server responses. When you reconnect, background sync updates other devices.

This means you can keep working offline, confident your data is safe and ready to sync later. Conflicts are handled by merging changes intelligently, respecting the on-disk contract.

Say you edit a task on your phone while offline. When you’re back online, the system quietly syncs, and your desktop sees the updated task instantly. No fuss, no delays.

When Local-First Architecture Might Not Be a Good Fit

While powerful, local-first isn’t for everyone. If your app demands real-time collaboration with low latency or complex conflict resolution, it might get tricky.

For instance, highly dynamic multiplayer games or systems needing instant server-side authority may struggle with local-first constraints. But for task management, note-taking, or project planning, it shines.

Understanding your use case is key. Threlmark’s design excels when offline speed, data portability, and simple collaboration matter most.

Getting Started with Threlmark and Local-First Thinking

Curious how to adopt this approach? Check out the Threlmark project on GitHub, which demonstrates the architecture in action. It’s a Next.js app that works directly with JSON files—no databases needed.

Start by structuring your data as files, then implement atomic writes and tolerant merges. Think of your disk as a contract, not just storage. This mindset simplifies many problems and opens new possibilities.

Visit Threlmark’s website for tutorials, and explore the code at GitHub.

Frequently Asked Questions

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

Threlmark reads the current file, merges changes intelligently—preserving unknown fields and bumping timestamps—and writes back atomically. Conflicts are minimized because each item is a separate file, reducing race conditions and overwrites.

Can I migrate existing data into Threlmark easily?

Yes. Since all data is stored as JSON files, you can write scripts or use existing tools to convert your data into the Threlmark layout. It’s designed for portability, so no lock-in or complex migration steps are needed.

What are the main advantages of a file-based system over traditional databases?

File-based systems are inspectable, portable, and interoperable. You can back up or move your data easily, work offline without restrictions, and avoid vendor lock-in. Plus, atomic file operations make data safe and consistent.

Is this approach suitable for real-time collaborative apps?

Local-first architectures excel in offline speed and resilience but face challenges with real-time collaboration at low latency. For highly dynamic, multi-user systems needing instant updates, additional sync layers or server authority might be required.

Conclusion

The core of Threlmark’s design is simple but profound: your disk is the contract. This shift empowers offline speed, data portability, and collaboration without complex infrastructure. It’s a reminder that sometimes, the simplest idea—making the disk the source—can rewrite the rules of software design.

Next time you’re designing an app, ask yourself: how can I treat the disk as the contract? That small change could lead to faster, safer, and more flexible workflows. Your data’s best home might be right on your own device, waiting for you to make it the foundation.