TL;DR
Threlmark’s core idea is that the disk’s JSON files serve as the single source of truth. This design simplifies sync, boosts reliability, and keeps your data portable. It’s a game-changer for building resilient, collaborative apps without a central database.
Imagine your project management app, but it lives completely on your disk—no cloud, no central server. Instead, your files are the source of truth, accessible and editable by any tool that can read JSON. That’s the core idea behind Threlmark’s architecture: the disk is the contract. It might seem simple, but it’s revolutionary.
In this deep dive, you’ll learn how treating the disk as the primary interface transforms development, collaboration, and reliability. We’ll explore the nuts and bolts of this approach and why it’s gaining momentum in the world of local-first apps.
Disk is the contract: inside a local-first roadmap hub
A Next.js app on top of plain JSON files — no database, no cloud, no accounts. The key decision: the on-disk layout IS the API. Everything else cascades from taking that seriously.
There is no server-of-record — the files are the record
The UI and any external tool reach the same files through the same discipline. The data root defaults to ~/.threlmark — home-based, because it’s a shared hub every one of your apps points at.
Inspectable
Every artifact is a file you can cat, diff, grep, commit.
Portable · no lock-in
Back up with cp, sync with Dropbox / git, migrate trivially.
Interoperable
Any tool in any language joins by reading / writing files.
Restartable
No in-memory state to lose — stateless over the files.
JSON file editor for Windows
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
Two disciplined patterns instead of a database
“Just use files” is easy to get wrong. These two patterns — ported from a battle-tested sibling app — are what make file-based state sound rather than reckless.
Atomic writes
Write to a temp file in the same dir, then rename() over the target. Rename is atomic on one filesystem — a crash mid-write leaves the complete old file or the complete new one, never a half.
The board heals itself
A single roadmap.json array races when two tools write at once. One file per card makes writes collision-free. Lane order lives in board.json and reconciles on read.
board.json. It writes an item file — the board fixes itself on Threlmark’s next read. Unknown keys are preserved, so the contract is forward-compatible.local-first database backup tools
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
The numbers can’t drift from the files
Anything computable from item state is computed — so the displayed numbers can never disagree with the underlying JSON. Priority is the clearest example: it’s calculated on read, never persisted.
priority — computed on read
Impact weighted heaviest; effort the only axis that subtracts. Reused verbatim from the original tool, so imported cards rank identically.
disk-based project management app
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
A handoff is a first-class flow event
The genuinely 2026-shaped part: most building is done by AI agents, so Threlmark closes the loop. Watch a card go from ranked to Done without anyone dragging it.
Handoff → report → self-move
The brief carries a reporting protocol. The agent reports through REST or the filesystem — and a done report moves the card itself.
POST /api/projects/:id/
items/:itemId/reportDirect call. Applied immediately.
drop reports/.json
→ ingested on read Robust even if the server’s down at finish time.
file synchronization software for JSON files
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
A small formula, and an honest hosting caveat
Because items are globally addressable (
Portfolio ranking — status-weighted
In-flight work floats to the top; bottlenecks cost the most, so blockers get nudged up.
Static read-only demo
Seeded data, writes to localStorage. Try-before-you-clone.
Personal Node instance
Password-gated, persistent backed-up THRELMARK_DATA_DIR.
Multi-tenant SaaS
Add accounts + per-tenant isolation. A separate build.
src/lib/*/store.ts is the natural seam — the same boundary that keeps the local tool simple is the one you’d extend for multi-tenancy. The architecture doesn’t fight that future; it just doesn’t pay for it until you need it.
Key Takeaways
- Treat the disk layout itself as the API—files are the source of truth.
- Use atomic file operations to prevent corruption and race conditions.
- Separate data into small, manageable JSON files for easy inspection and merging.
- Sync by copying files, not via a central server, enabling offline work.
- Conflict resolution relies on timestamps and flexible merge strategies.
What ‘Disk Is the Contract’ Really Means in Practice
At its heart, Threlmark treats the on-disk file structure as the *ultimate authority*. Instead of a database that you query via an API, your data lives in plain JSON files. Think of it as a contract that everyone respects—files are the source of truth, and all tools read and write them directly.
For example, when you update a task in Threlmark, it writes directly to a specific JSON file. No server, no special database. Your editor, a sync tool, or even a script can see the exact same data, because it’s all in those files.
This approach makes debugging easy: just `cat` the JSON files or diff two versions. It’s like having a living, breathing document that’s always up-to-date and transparent.
Why a JSON-on-Disk Model Makes Life Easier for Developers
JSON files are human-readable, easy to manipulate, and widely supported. Learn more about curated lists and reviews. Instead of guessing what a database schema looks like, developers can peek directly into the files. Need to debug? Open the JSON in your editor and see the exact state.
Imagine you’re working on a project where each task is a file named after its ID, stored under `items/`. Updating a task is as simple as editing a JSON file and saving it. No locks, no complicated transactions.
This simplicity speeds up development and reduces bugs. Plus, since files are atomic units, updates don’t clobber each other—no race conditions.
How Threlmark Handles Concurrency and Sync Without a Central Database
Concurrency in a disk-based system sounds tricky, but Threlmark keeps it simple with atomic file writes. When you save a task, it writes to a temporary file, then renames it—an atomic operation that prevents partial writes or corruption.
Syncing across devices happens by copying these JSON files. When your device reconnects, Threlmark compares files and merges changes. Conflicts are resolved based on timestamps or user-defined rules, much like how Git handles merges.
For example, if two devices edit the same task offline, the system can detect conflicts and ask you to choose which version to keep, or automatically merge simple changes.
How Threlmark’s Structure Facilitates Collaboration and Multi-Device Work
Collaboration becomes straightforward because every device reads and writes the same set of JSON files. No central server or API is needed. Your files are the shared language, and tools like Dropbox or Syncthing keep them in sync.
For example, a team member can add a new feature card on their laptop, and when they save, the file updates. Another team member’s device picks up the change during sync, and the card appears instantly.
This model also respects privacy and security—since data is stored locally, you control exactly what’s shared and when.
The Real Benefits of ‘Disk Is the Contract’ for Reliability and Resilience
When your data’s in plain files, you can back it up, migrate it, or inspect it anytime. If your device goes offline or crashes, your data isn’t lost—just reopen the files and pick up where you left off.
Imagine working on a project while traveling, with no internet. Your files are local, accessible, and ready to go. Once you reconnect, sync merges your changes, and your work continues uninterrupted.
This approach makes apps more resilient—no server downtime or network issues can halt your progress.
Tradeoffs and Why It’s Still Not for Everyone
While the disk-as-contract approach has many perks, it’s not perfect for every scenario. Large datasets can slow down file operations, and conflict resolution can become complex with many concurrent edits.
Imagine a team working on a massive project with thousands of JSON files—performance might suffer. Also, without a central database, enforcing strict data integrity rules gets trickier.
It’s a powerful method for personal projects or small teams, but might need adjustments for enterprise-scale apps.
How to Start Using ‘Disk Is the Contract’ in Your Projects
- Design your data as JSON objects stored in files, one per item.
- Use atomic write patterns—write to temp files, then rename.
- Keep your folder structure simple and consistent.
- Implement syncing with tools like Dropbox or Syncthing.
- Handle conflicts by timestamps or user prompts.
Frequently Asked Questions
What does ‘disk is the contract’ really mean?
It means the on-disk JSON files are the definitive source of truth. All tools, sync, and recovery depend on these files, making the disk the ultimate interface for your data.How is this different from a normal client-server app?
Instead of relying on a remote database, all data lives locally as files. Syncing happens by copying files between devices, not querying a central server.Why use JSON on disk instead of a database?
JSON files are simple, readable, and easy to manipulate. They make debugging, backup, and migration straightforward without the complexity of a database system.How does sync work when devices reconnect?
Changes are merged by comparing files, resolving conflicts with timestamps or rules. Sync tools like Dropbox facilitate seamless updates across devices.What happens if two devices edit the same file offline?
Threlmark detects conflicts during sync and can prompt you to choose the preferred version or merge simple changes automatically.Conclusion
In a world dominated by central servers and complex databases, Threlmark’s approach flips the script. By making the disk itself the contract, you gain transparency, resilience, and portability. It’s a simple idea with profound implications for building trustworthy, collaborative apps.
Next time you think about data storage, ask yourself: what if the files on my disk were the only thing I needed? That’s the power—and the promise—of ‘disk is the contract.’
