TL;DR
Threlmark’s architecture treats local disk as the primary source of truth, enabling offline access, easy syncing, and complete data control. This approach simplifies development and enhances user trust by making files the contract for all data operations.
Imagine a project management tool that works beautifully even without internet. No cloud, no login, just your files. That’s what Threlmark delivers with its local-first architecture. It’s a simple idea—your disk is the contract—that flips traditional cloud models on their head.
This setup isn’t just about offline mode; it’s about trust, control, and making data portable. In this article, I’ll walk you through how Threlmark’s unique approach to file-based data management powers a flexible, resilient, and user-centric system. Learn more about private placement markets and related strategies.
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.
MAIWO 4 Bay NVMe Cloner Duplicator with Cooling Fan, USB4.0 NVMe PCIe Dock SSD Reader, Supports 1-to-3 Offline Clone & Software RAID,40Gbps High Speed, Backward Compatible Thunderbolt 4/3
【4-Bay M.2 NVMe SSD Dock with Cloning Capabilities & Cooling Fan】Supports software RAID,which is a high-performance storage solution…
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 Data Storage in Kotlin: Managing Databases in Android Environments (The Android Developer's Playbook)
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.
Python in Action: 60 Mini Projects to Automate Everything (Part 1): Practical CLI Tools, File Automation, and Data Cleaning with CSV, Excel, and JSON
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.
disk-based data synchronization tool
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 your disk as the primary source of truth—files are your API, making data transparent and portable.
- Atomic file writes prevent corruption during crashes, ensuring data safety.
- One file per item simplifies concurrency and conflict resolution.
- Background sync allows offline use and device-to-device updates without complex server dependencies.
- Design your app to read, merge, and write files—avoiding lock-in and easing future upgrades.
What Does ‘Disk Is the Contract’ Actually Mean?
At its core, ‘disk is the contract’ means that the files on your disk are the definitive source of truth. Unlike traditional apps that rely on databases or cloud servers, Threlmark treats files as the actual API.
For example, each card in your project has its own JSON file in a dedicated folder. When you open the app, it reads these files directly. When you update a card, it writes back to the file—atomically, so no partial updates or corruption.
This approach guarantees that what’s on disk is always right. There’s no hidden state, no backend to break, just files you can open, edit, or sync with any tool that understands JSON. For more on data management, visit local-first architectures.
How Threlmark’s File Layout Creates a Rock-Solid Data Pact
Threlmark’s on-disk layout isn’t a random folder dump. It’s a carefully designed contract—every file has a purpose, and the structure guides how data flows. Read about file layout design for robust data systems.
At the root, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project gets its own folder with metadata (`project.json`), lane order (`board.json`), and one file per card in `items/`. Suggestions, handoffs, reports, and shared items all have dedicated folders.
This setup means every artifact is a file you can open and inspect. It’s portable—copy the entire folder, sync via Dropbox, or migrate to a new device—without losing any info.
Why This File-Based Approach Is Safer Than Databases
Databases are complex beasts—lock files, transactions, and sometimes hidden corruption. Threlmark sidesteps that with atomic file writes.
Every change writes to a temp file, then renames it atomically. If your system crashes mid-write, you’re either left with the old file or the new one—never a half-baked mess. Discover more about atomic file operations.
Plus, updates use read-merge-write logic: read current files, merge changes, write back atomically. This makes concurrent edits safe and predictable.
How One File Per Card Keeps Things Simple and Safe
Instead of one big `roadmap.json`, Threlmark uses one JSON file per card. This might seem small, but it’s a game-changer for concurrency and clarity.
If two tools want to update different cards, they do so independently. No locks, no conflicts—just atomic saves.
The lane order lives in `board.json`, but it’s read and reconciled against actual items every time. If a card is deleted, the lane order self-heals, keeping data consistent without manual cleanup.
How Sync Works — Background, Not Central
Threlmark’s sync isn’t a constant ping to the cloud. It’s a background process that copies files between devices or to a server, whenever available.
This means your data is always on your device, ready to go—even offline. When a change happens, it’s just another file update, which syncs in the background.
This approach makes everything faster and more reliable. No waiting for a server to respond, no downtime if the internet drops.
What Are the Real Benefits of a Local-First System?
Speed, privacy, and resilience—Threlmark’s approach delivers all three. You get instant access to your data, even offline. Your files aren’t stored on some third-party server, so your privacy stays intact.
Think of a designer working on a plane—no internet, no problem. Or a developer syncing with a laptop and desktop without hassle. The system just works, no matter what.
Plus, because everything’s files, it’s easy to backup, migrate, or share your data with other tools.
What Developers Love About This Approach
For developers, Threlmark simplifies state management. No complex database migrations, no ORM headaches. Just files, which are easy to version control and manipulate.
This architecture reduces backend complexity, cuts costs, and makes collaboration smoother. When you want to add a new feature, you just read and write files—no need to design new APIs or worry about server load.
Plus, the open format means anyone can extend or integrate with Threlmark easily.
What Are the Tradeoffs? Is It Perfect?
No system is without compromises. Managing sync conflicts, schema evolution, and operational complexity can be tricky.
Threlmark handles conflicts with merge logic, but in larger teams, conflicts might become more frequent. Schema changes require careful planning to avoid data loss.
Yet, these tradeoffs are often worth it for the speed, control, and offline reliability you gain.
Could You Build Your Own Local-First App Like Threlmark?
Absolutely. The core principles are straightforward: treat your disk as the source of truth, write atomic file operations, and design your app to read and write individual files.
Start small: build a simple app that stores data as JSON files. Use atomic writes and conflict resolution from the start. Over time, you can add sync and collaboration features. Check out private equity insights for more on building scalable systems.
Check out Threlmark’s open-source code for inspiration [here](https://github.com/MeyerThorsten/threlmark).
Frequently Asked Questions
What exactly does ‘disk is the contract’ mean?
It means that the files stored on your device are the definitive source of truth. The app reads and writes these files directly, so they define the system’s state, not a database or server.
How does syncing work across multiple devices?
Syncing happens in the background by copying and merging files. Each device updates its own files locally, then syncs those files with others using a background process, so data stays consistent without user intervention.
What happens if two devices edit the same card at once?
Threlmark uses merge logic—reading current files, combining changes, then writing back atomically. Conflicts are minimized, and when they do occur, the system helps resolve them smoothly.
Is this approach secure and private?
Yes, because data stays on your device unless you choose to sync or share. No secret cloud storage or third-party servers hold your info unless you set it up that way.
Can I build my own system like this?
Definitely. The key is to treat your disk as the API, use atomic writes, and design for mergeability. Starting small and expanding over time makes it manageable.
Conclusion
When you make disk the contract, your app becomes more resilient, transparent, and user-focused. It’s a simple idea with powerful implications—trust your files, and the system will follow.
Imagine a world where your data always stays in your control, ready to move or share at a moment’s notice. That’s the promise of Threlmark’s approach—and a future worth building for.
