Ever wonder how some apps seem to work perfectly offline, sync seamlessly across devices, and stay simple under the hood? Threlmark’s secret is its radical approach: it treats your disk as the contract for all data. No server, no cloud, just files. That’s it. And it’s powerful. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

In this article, you’ll see how this design flips the usual model on its head. You’ll learn why the on-disk layout is the heartbeat of the system, how it makes data safe and portable, and what it means for developers who want a simpler, more resilient way to build project tools.

Key Takeaways

• Threlmark’s core idea is using the disk layout as the single source of truth, simplifying data management.
• Atomic file writes prevent corruption and make the system restartable without complex lock mechanisms.
• Single-file per item prevents conflicts and race conditions during concurrent updates.
• Self-healing board files keep the workflow consistent and tidy without manual intervention.
• Open JSON files allow any external tool or AI agent to participate effortlessly, fostering collaboration.

How Threlmark Turns Your Disk Into the Single Source of Truth

Threlmark’s architecture is built on one simple idea: the files on your disk are the database. Each project, card, and even the flow of work lives as a JSON file. This means every change, every update, is just a file write. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

Imagine editing a task directly in your file explorer—your app reads and writes files in a predictable, atomic way. No server needed. No complex syncing protocols. Just a folder full of JSON files that represent your entire project ecosystem.

For example, your project folder might look like this:

• threlmark.json: your manifest
• items/123.json: a task card
• board.json: your lane order

All these files are the contract—if you change them, your app reflects those changes immediately.

Why This Simple Disk Approach Makes Everything Easier

Using files as the source of truth isn’t just elegant—it solves real problems. First, it makes your data portable. Copy the whole folder, and you have your project. No database migration or complex export needed. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

Second, it’s super safe. Because every write is atomic, you never get a corrupted file. And if your app crashes mid-save, the old data remains intact. Think of it like a safety net for your work.

Third, it’s open and interoperable. Any tool that can read and write files can join your project. Want to hack on your data with a script? Just modify JSON files. Need to migrate to another system? Copy and go.

How Threlmark Ensures Data Safety with Atomic Files

Atomic writes are the backbone of safe file-based data. Instead of overwriting a file directly, Threlmark writes to a temporary file first. Only after the write completes does it rename the temp file over the original. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

This process guarantees that you never end up with a half-written or corrupt file, even if your system crashes. Imagine saving a big document—your app does the same, replacing only when the data is fully written.

For example, updating a task involves writing a new JSON to a temp file, then renaming it. This simple step makes your data resilient and trustworthy.

The One File Per Item Strategy: No Collisions, No Claps

Instead of a giant list of tasks in one file, Threlmark keeps each task as its own JSON file in the items/ folder. This prevents race conditions when multiple tools update different cards at the same time. Disk Is the Contract: Inside Threlmark’s Local-First Architecture

Think of it like a deck of index cards—each one stands alone, easy to read or change without disturbing the others. The folder contains all current tasks, with the app reading and writing individual files as needed.

Plus, the system self-heals: whenever you load your project, it checks that all cards listed in board.json actually exist in items/. Missing cards are ignored or cleaned up, keeping everything consistent.

How the Board Self-Heals and Keeps Your Workflow Smooth

The board.json file tracks your lane order and task statuses. But it doesn’t just sit there. Every time you load your project, Threlmark compares the list with actual task files. Missing or orphaned cards get cleaned up automatically.

This means your workflow stays clean and accurate without manual cleanup. It’s like having a smart editor that always keeps your task board tidy—even if you accidentally delete a card or get out of sync.

For example, if a task file is deleted outside the app, the next load automatically removes it from the board, preventing clutter and confusion.

Making Files Play Nicely with External Tools and AI Agents

Because the data lives as plain JSON files, any tool or AI agent can join in. No special API or database commands needed. Just read, modify, and write files. List of

This openness allows external tools like IdeaClyst or custom scripts to participate. For example, an AI agent can analyze your tasks, suggest improvements, and move cards to ‘Done’—all by editing JSON files directly.

It’s like giving everyone a shared notepad instead of a locked cabinet. Collaboration becomes frictionless and transparent.

Sync Without a Server: How Threlmark Handles Offline and Multiple Devices

Threlmark’s local-first approach means your data is always on your disk. When devices connect, you sync changes by copying files between folders or using sync tools like Dropbox or Syncthing.

Imagine working on your laptop at home, then picking up your tablet—your JSON files stay the same. When connected, your files sync in the background, keeping everything up to date.

This model makes your app resilient to outages. You can work offline for days, then sync when you’re back online—no fuss.

Practical Tips for Building Your Own Disk-First App

1. Use atomic writes: Always write temp files and rename to avoid corruption.
2. Keep each item in its own file: Prevent race conditions and make updates simple.
3. Implement self-healing: Reconcile your folder contents on load to keep things tidy.
4. Make data portable: Use JSON files so tools can read and write your data easily.
5. Design for offline: Sync changes via file copying, not just online updates.

Frequently Asked Questions

How does Threlmark handle conflicts when multiple tools update the same file?

Threlmark uses atomic writes on individual files, so conflicts are rare. It relies on read-merge-write patterns, and if conflicts occur, last-write-wins. For more advanced conflict resolution, custom merge strategies can be added.

Can I use Threlmark with other tools like Notion or Trello?

Yes. Since all data is stored as JSON files, you can sync or import/export with other tools. Threlmark’s open format makes integration straightforward, especially when combined with file sync tools like Dropbox or Syncthing.

What happens if a file gets corrupted or lost?

Because each item is a separate JSON file, corruption is localized. Restoring from a backup or a previous version of the file system can recover lost data. Atomic writes also minimize the chances of corruption happening in the first place.

Is this approach suitable for large projects?

For very large projects, managing thousands of JSON files can become cumbersome. However, with careful organization and indexing, the approach scales well, especially for teams that value transparency and offline access.

How does Threlmark’s architecture compare to traditional databases?

Unlike databases, Threlmark avoids the complexity of server management, migrations, and lock-in. It focuses on simplicity, portability, and offline resilience, making it ideal for personal, small-team, or hybrid workflows.

Conclusion

Threlmark’s disk-as-contract approach shows that simplicity and transparency beat complex databases every time. By making your data files the source of truth, you gain control, resilience, and flexibility.

Imagine a project tool that’s as easy to hack as editing a text file—no lock-in, no cloud dependency. That’s the power of thinking of your disk as the contract. Your next project might just be a folder away.