Imagine a project tool that’s so simple, it runs entirely from a folder full of JSON files on your desktop. No cloud, no server, no locked-in database. Just your data, plain and clear. That’s what Threlmark does, and it’s a game-changer for anyone tired of siloed, fragile project management systems.

This article pulls back the curtain on its architecture. You’ll learn why “disk is the contract” isn’t just a buzzword — it’s a radical shift in how to build reliable, flexible apps that work everywhere, offline or online. If you’re curious how a simple file layout can power complex AI workflows, keep reading. This is about smarter, safer data — on your terms.

Key Takeaways

• Design your app so the on-disk files *are* the API — simple, transparent, and extendable.
• Use one JSON file per item with atomic write patterns to prevent corruption and conflicts.
• Leverage tolerant merging to evolve data formats without breaking existing tools.
• Build self-healing views that reconcile filesystem state on each load for accuracy.
• External tools and AI agents can participate effortlessly by just reading/writing files.

What does ‘disk is the contract’ really mean?

At its core, ‘disk is the contract’ means that your app’s entire data state lives in files that are both the source of truth and the interface. Think of it like a shared document everyone can edit, trust, and extend. Threlmark’s files aren’t just storage — they’re the API, the data, and the collaboration layer wrapped into one.

For example, each project card lives as a separate JSON file in `items/`. When you open your app, it reads those files. When you update a card, it writes a new file atomically. No database, no complicated synchronization protocol, just plain files that any tool can read or write.

How file-per-item architecture keeps data safe and flexible

Using one JSON file per item might sound primitive, but it’s a masterstroke for safety. Each write is atomic, meaning it either completes or doesn’t happen at all. You never get corrupted data, even if your system crashes mid-save.

Plus, this setup makes it super easy to merge changes. If two tools update different cards simultaneously, they won’t overwrite each other. Instead, they write their own files, and the system can reconcile differences later.

Take, for example, how Threlmark handles concurrency: when a user drags a card to a new lane, it updates a single file. Meanwhile, an AI agent might add a comment to a different card. Both actions are atomic, safe, and easy to track.

Why the on-disk layout acts as the API — not just storage

In Threlmark, the folder structure isn’t just storage; it’s the way external tools interact. The manifest (`threlmark.json`) declares the system, while each project’s `project.json`, `board.json`, and item files describe the current state. This means anyone can extend or automate the system just by reading or writing files. Learn more about local-first architecture.

For instance, an AI assistant can scan `items/`, find cards marked as ‘next’, and move them to ‘done’ by simply editing a file. No special APIs, no server calls. The format is stable, predictable, and human-readable.

How making state restartable keeps your data safe and portable

Since all state lives in files, Threlmark can restart instantly. No in-memory database to worry about. Just reload files, and everything is back. This makes backups and migrations trivial — copy a folder, and you clone your entire system.

Imagine handing your project folder to a new laptop. Everything, including your AI workflows and shared cards, just works. No complicated export or sync — just a copy-and-run approach.

This simplicity is powerful. It means your data isn’t locked into a proprietary database. It’s transparent, portable, and resilient against crashes.

How atomic writes and tolerant merging make your data safe

Threlmark employs two key patterns to keep data safe. First, **atomic writes**: files are written to a temporary file and then renamed. This guarantees that you never see a half-written or corrupted file.

Second, **tolerant merging**: when updating a file, the system reads the current version, merges in changes, and writes back. It preserves unknown fields and defaults missing ones, making future updates seamless and forward-compatible.

For example, if a new feature adds a `priority` field to cards, older tools ignore it, and newer tools preserve it even if the old code doesn’t recognize it. This flexibility is essential for evolving systems.

How self-healing boards keep your project view accurate

Threlmark’s `board.json` lists items per lane. But it doesn’t just store static order — it **self-heals** on read. Every time you open your project, the system compares the board with actual item files.

If a card was deleted or moved outside the interface, the system detects and corrects discrepancies. This prevents stale or broken views, keeping your project clean and reliable.

Imagine dragging a card into a new lane. The system updates `board.json`, but if someone deletes that card from `items/`, the next time you load, it’s gone from the view, no manual cleanup needed.

How external tools and AI agents can participate effortlessly

Because the data is just files, any tool can join the party. Want to automate task creation? Just write a new JSON file in `items/`. Need to move a card? Edit the relevant file. Discover how disk as the contract enables seamless automation.

AI agents, like those integrated with Threlmark, can scan files, analyze priorities, and update cards without special APIs. They operate by reading and writing files — simple, universal, and safe.

For example, an AI could automatically mark high-priority bugs as ‘done’ after a test run, by just changing a file in the filesystem. No server, no API, just file manipulation.

What it takes to build your own disk-is-the-contract app

If you want to follow Threlmark’s approach, start with a clear directory layout: a manifest, project folders, and one JSON per item. Use atomic write techniques — write to a temp file, then rename. Check out more on local-first systems.

Implement tolerant merging that preserves unknown fields and defaults missing ones. Make your system self-healing by reconciling views with actual files on every read.

And remember: keep everything stateless over the filesystem. Your app should just read, merge, and write files, avoiding complex in-memory state.

When ‘disk is the contract’ isn’t the right choice

While this approach is powerful, it’s not always perfect. For apps needing real-time collaboration with low latency, or where data must be synced across many devices instantaneously, a more traditional server-based system might suit better. Learn about home theater and AV setup tips for related tech insights.

It also demands discipline: everyone must follow the same file structure and merging rules. If your team isn’t on board, chaos can follow.

So, assess your needs carefully. For solo projects, offline work, or transparent workflows, this is gold. For high-frequency multi-user apps, consider hybrid approaches.

Frequently Asked Questions

What does ‘disk is the contract’ mean in plain English?

It means your app’s data lives in files that are both the source of truth and the way external tools interact. The files themselves define how the app works, making everything transparent and simple.

How is local-first different from offline-first?

Local-first means the app always works from local data, even when online. Offline-first emphasizes working offline and syncing later. Local-first is about the design priority, while offline-first is a feature that follows.

What happens when two devices edit the same data?

Because each change is a separate file and updates are atomic, conflicts are minimized. When conflicts occur, the system can reconcile by merging or prompting the user, depending on complexity.

How do apps handle sync failures or conflicts?

Threlmark’s approach makes conflicts rare. When they happen, the system’s tolerant merging preserves unknown fields, and self-healing views keep the project accurate. Manual intervention is rare.

What data lives on the device vs. the server?

All your project data lives locally in JSON files. The server’s role is mainly for sync, backups, and collaboration, not as the primary data store.

Conclusion

Threlmark’s local-first architecture proves that simplicity and transparency can power complex workflows. By making the disk the contract, you gain safety, portability, and interoperability — all without a single database or server.

Imagine your next app running flawlessly from a folder full of JSON files, ready for any tool, any device, any AI. That’s the power of a system built on trust in the humble file.