TL;DR
Threlmark’s ‘Disk Is the Contract’ design makes disk storage the ultimate authority for data. It simplifies sync, enhances privacy, and keeps your tools portable—all without a database or cloud dependency.
Ever wonder if your data could be safer, more private, and easier to manage? Threlmark’s architecture shows us how a simple idea—making disk storage the core of everything—can flip traditional app design on its head. Learn more about local-first architecture.
Instead of relying on servers or cloud databases, Threlmark treats your disk as the ultimate contract. This approach isn’t just about storage; it’s about building a resilient, flexible system where your data stays in your control, everywhere you go. Ready to see how?
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.
SANDISK 1TB Extreme Portable SSD (Old Model) – Up to 1050MB/s, USB-C, USB 3.2 Gen 2, IP65 Water and Dust Resistance, Updated Firmware – External Solid State Drive – SDSSDE61-1T00-G25
Get NVMe solid state performance with up to 1050MB/s read and 1000MB/s write speeds in a portable, high-capacity…
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.
SANDISK 128GB Ultra Flair USB 3.0 Flash Drive, SDCZ73-128G-G46, Black
High-speed USB 3.0 performance of up to 150MB/s(1) [(1) Write to drive up to 15x faster than standard…
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.
BUFFALO LinkStation 210 2TB 1-Bay NAS Network Attached Storage with HDD Hard Drives Included NAS Storage that Works as Home Cloud or Network Storage Device for Home
Value NAS with RAID for centralized storage and backup for all your devices. Check out the LS 700…
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.
Music Studio 11 – Music software to edit, convert and mix audio files – Eight music programs in one for Windows 11, 10
8 solid reasons for the new Music Studio 11!
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 as the single source of truth—every artifact is a plain JSON file.
- Use atomic write patterns to prevent corruption and ensure data safety.
- Maintain one file per item to avoid race conditions and enable concurrent updates.
- Design systems to reconcile and self-heal on each load, keeping data consistent.
- External tools can participate naturally through simple file read/write operations.
How ‘Disk Is the Contract’ Changes Everything in Data Management
In Threlmark’s world, your disk isn’t just storage—it’s the single source of truth. This means every piece of data lives as a plain JSON file, readable and manageable by any tool. No database, no cloud, just files you can open and understand. For example, each roadmap card is a separate file in the items/ directory, making data inspection straightforward.
This setup lets you back up, sync, or migrate data with a simple copy, similar to the principles discussed in local-first architecture. If your disk copies are intact, so is your entire system. It’s like having your entire project’s brain on a USB stick.
Why does this matter? Because traditional databases often introduce complexity—schemas, migrations, and vendor lock-in—that can make data fragile or hard to interpret outside the specific environment. You can explore similar concepts in local-first data management. By contrast, plain files are transparent, versionable, and easily manipulated with standard tools. This transparency enables a deeper understanding of your data, making debugging and auditing more straightforward, ultimately leading to more resilient systems that are less dependent on proprietary software.
Why Keeping Data on Disk Is Smarter Than Cloud-Heavy Apps
Traditional apps store data in the cloud, which can slow down your work and expose your info. Threlmark flips this by making your local disk the main hub. Imagine editing a roadmap while offline, then syncing it later—your data is always at your fingertips.
For example, when you update a card, the system writes a new JSON file atomically, ensuring no corruption—even if your laptop crashes mid-save. This approach guarantees safety and speed, especially without an internet connection.
But why is this smarter? Because relying solely on cloud storage introduces latency, privacy concerns, and potential outages. Local-first architecture reduces these risks by prioritizing your device as the primary source. This means you can work seamlessly offline, trust your local copy, and only sync when convenient. The tradeoff is that you need disciplined handling of local data—ensuring proper syncing and conflict resolution—but the payoff is greater control, speed, and privacy, especially critical for sensitive or critical applications.
How Atomic File Writes Keep Your Data Safe and Consistent
Atomic writes are the backbone of Threlmark’s reliability. Discover more about atomic file operations. When you save a file, it first writes to a temp file, then renames it—this way, your data never ends up half-written or corrupted.
Picture editing a roadmap card. The system creates a temporary copy, then swaps it in seamlessly. Even if your computer crashes, your data remains consistent, ready for the next session.
This atomic operation is crucial because it prevents scenarios where partial writes could leave your data in an inconsistent state—like a half-finished update that corrupts the entire file. By ensuring that each write is completed fully or not at all, the system maintains integrity, which is vital for trustworthiness, especially when multiple tools or processes might access the files concurrently. The tradeoff is that atomic operations can be slightly slower than simple overwrites, but the increased safety and consistency are well worth it, particularly in environments where data integrity is paramount.
One File per Item: How Threlmark Avoids Race Conditions
Instead of a giant JSON array, each roadmap card gets its own file, exemplifying the file-per-item approach. This reduces conflicts—multiple tools can update different cards without stepping on each other.
For example, if your AI assistant moves a task to ‘Done,’ it just overwrites that card’s file. No locking needed, no chance of overwriting someone else’s change.
This approach significantly diminishes race conditions because each item is isolated. Multiple processes or users can work on different files simultaneously without risking overwrites or data corruption. It also simplifies conflict resolution—if two tools modify different files, they won’t interfere. However, this design assumes a well-structured directory system and disciplined file management, which can add complexity but pays off in robustness and scalability. The tradeoff is increased file management overhead, but the benefit is a more resilient, concurrent editing environment that aligns well with modern distributed workflows.
How the System Self-Heals and Keeps the Board in Sync
The lane order isn’t stored in a single file. Instead, it’s a list of IDs that gets reconciled each time you load your project, similar to strategies discussed in self-healing data systems. If a card gets deleted or moved outside the system, the board automatically adjusts.
Imagine opening your project and seeing a clean, up-to-date view of all tasks—no manual fixing needed. This self-healing makes your project resilient to external changes.
This reconciliation process is crucial because external modifications—whether accidental or intentional—could otherwise cause inconsistencies. By reading the current state of each file and comparing it to the in-memory model, the system can detect discrepancies and correct them on load. This ensures that the project always reflects the true state of the data, reducing manual maintenance and preventing broken workflows. The tradeoff is that it requires careful design to handle conflicts gracefully, but the benefit is a robust, self-maintaining system that adapts to external changes without user intervention.
How External Tools and AI Agents Play Nice with Files
External tools like IdeaClyst or AI code agents can directly read or write JSON files without permission hurdles. They just follow the same discipline—treat the disk as the contract.
For example, an AI can suggest a new task, save it as a JSON file, and the system will pick it up on the next load. No API calls or complex integrations needed.
This direct approach empowers external tools by reducing barriers to integration. They operate on the same principles: read, modify, write. This simplicity means that AI agents or third-party tools can participate in your workflow without proprietary SDKs or complex APIs, making the system more open and flexible. However, it also requires discipline—external tools must respect the file conventions and atomic operations to avoid introducing inconsistencies or corruption. The tradeoff is that while this approach maximizes flexibility, it demands careful coordination and disciplined file management to prevent conflicts or data loss.
Practical Tips to Build with ‘Disk Is the Contract’ Philosophy
- Use atomic `rename()` for all file writes—never overwrite directly.
- Organize your data with one file per item for easy concurrency.
- Keep directory structures clear: separate active, shared, and archived items.
- Implement read-merge-write cycles to allow extension and forward compatibility.
- Design your apps to reload data from disk frequently to stay in sync.
What This Means for You, the Developer or Power User
Choosing a disk-based contract shifts control back to you. You can back up, sync, or tweak your data with simple tools. No vendor lock-in, no cloud dependency.
If you’re building tools, you get a transparent, resilient, and extendable foundation. For users, it means more privacy, fewer surprises, and better offline support.
Frequently Asked Questions
What exactly does ‘Disk Is the Contract’ mean?
It means your application’s core data lives on your local disk as plain files, and this disk state is considered the definitive record—no external database or server needed.
How does local-first architecture differ from traditional cloud-based models?
Local-first relies on storing and managing data primarily on your device, syncing it when needed, instead of depending entirely on cloud servers. It improves speed, privacy, and offline capability.
What are the main technical challenges in implementing this approach?
Ensuring atomic writes, handling concurrent updates gracefully, and designing self-healing synchronization are key challenges—but they’re manageable with disciplined file operations and read-merge cycles.
How does data synchronization work across multiple devices?
Data is stored as files on disk. When syncing, tools compare file states, resolve conflicts via versioning or merging, and keep everything consistent without complex protocols.
Is this approach suitable for enterprise applications or only personal use?
It’s suitable for both. Many enterprises adopt local-first principles for privacy and resilience, especially with tools that support conflict resolution and secure syncing.
Conclusion
Making the disk the contract turns your data into a living, breathing part of your workflow. It’s about control, safety, and simplicity—all without losing flexibility.
Next time you build or tweak your tools, remember: a plain disk isn’t just storage. It’s the foundation for resilient, portable, and future-proof applications. Your data’s best home might just be right there, waiting on your local drive.
