TL;DR
Threlmark’s local-first architecture treats disk storage as the ultimate source of truth. This approach makes data portable, safe, and easy to sync across devices without relying on a central database. It’s a game-changer for offline-first apps and multi-device workflows.
You’ve probably used apps that slow to a crawl when offline or get confused with conflicting data. Threlmark flips that script. It’s built from the ground up on a simple idea: the disk is the contract.
Instead of a complicated server or locked-in database, Threlmark relies on plain JSON files stored on your local disk. This makes the system fast, reliable, and super portable. In this article, I’ll show you how that one decision cascades into everything — from data integrity to seamless multi-device workflows. If you care about understanding the nuts and bolts of modern, resilient apps, stay with me.
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.
Mobile App Offline Data Strategies: Expert Approach for Reliable Operation Without Network Access (Practical Mobile, Python & Robotics Engineering Series)
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.
REXBETI 25Pcs Metal File Set, Premium Grade T12 Drop Forged Alloy Steel, Flat/Triangle/Half-round/Round Large File and 12pcs Needle Files with Carry Case, 6pcs Sandpaper, Brush, A Pair Working Gloves
all the 16 pieces file are made by T12 Drop Forged Alloy Steel, the long lasting teeth were…
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.
The First 90 Days: Proven Strategies for Getting Up to Speed Faster and Smarter, Updated and Expanded
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.
MFi Certified USB 3.0 Flash Drive 128GB for iPhone, 3in1 External Memory Photo Keeper Storage Stick for Picture/Video/Data Saver/Backup, High Speed Thumb/Jump/Hard Drives for iPhone/iPad/Android/PC
【MFi Certified Multi-function Flash Drive】This flash drive is MFi certified, high quality and excellent performance, allowing you to…
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 ultimate contract: store each piece of data as a separate, atomic JSON file.
- Atomic writes prevent corruption, making your data safe even during crashes or power failures.
- One file per item simplifies concurrency and reduces race conditions.
- Folder structures act as a formal agreement—easy to backup, migrate, and extend.
- Sync across devices by sharing folders—no need for custom protocols or servers.
Why Making Disk the Contract Changes Everything
When your app treats the disk as the ultimate source of truth, it gains a natural, rock-solid foundation. Threlmark’s approach means all data is stored directly on your device in a simple folder structure. There’s no middleman, no server to sync with — just files.
This setup makes data portable and transparent. You can easily back up, move, or inspect your JSON files. Plus, the app becomes inherently offline-first. Need to work without internet? No problem. When you reconnect, syncing is straightforward because everything’s just files.
Imagine you’re working on a project while flying. When you land, plug into Wi-Fi. Threlmark automatically syncs the changes—no fuss, no conflicts, just updates. This is the power of the disk-as-contract approach.
How Threlmark’s File Structure Acts Like a Legal Contract
Threlmark organizes its data into a clear folder layout, almost like a legal agreement between the app and your files. At the root, you find a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project gets its own folder with metadata, lane order, and a file per roadmap item. For more on how this structure works, see Disk Is the Contract.
For example, each card lives in the `items/` folder as a separate JSON file. External suggestions go into `suggestions/`, and completed work lands in `reports/`. This structure means every piece of data is a standalone file you can open, diff, or back up. It’s a transparent contract that any tool can understand and modify.
This setup keeps everything consistent, portable, and resilient. If you want to move your project elsewhere or automate updates, it’s just copy-paste or script away. That’s the beauty of treating files as the record.
Making File-Based State Safe and Reliable
File safety is key—nothing destroys a system faster than corrupt data. Threlmark uses atomic writes: save data to a temporary file, then rename it. This guarantees that if your system crashes mid-write, your files stay consistent. Learn more about local-first architecture at The Idea Magazine.
For example, when saving a card, the app first writes `card123.json.tmp`, then renames it to `card123.json`. This simple step prevents half-written files from corrupting your data. It’s a technique borrowed from battle-hardened software, and it pays off.
Additionally, updates use a read-merge-write cycle. They read the current file, merge in changes, and write back atomically. This approach preserves important metadata like creation date and avoids overwriting unknown fields. It makes your data forward-compatible and less prone to bugs.
One File Per Item: Why It Beats a Big Array
Some tools cram all your roadmap cards into one big JSON array. That’s easy to read but deadly for concurrency. Threlmark solves this with **one file per item**. Each card is its own JSON file, like a tiny document. For more on file-based data management, see Disk Is the Contract.
This makes updating a single card a breeze—just write that one file. No need to load, modify, and rewrite the entire list. It’s faster, safer, and better for collaboration.
Plus, the folder of items auto-heals itself. When you load the project, it checks which files are missing or orphaned, then syncs the folder to match. This keeps your data tidy and consistent, even when multiple tools or devices are involved.
How Threlmark Syncs Data Across Devices Without a Server
Threlmark’s architecture naturally supports syncing because it treats the disk as the single source of truth. When you connect a new device, it simply copies the entire folder structure. No complicated API or sync protocol needed. See more about local-first sync.
Imagine you have a laptop and a tablet. Both point to the same folder, say via Dropbox or Syncthing. Changes made on one device instantly appear on the other once the sync runs. No special server required.
Sync conflicts? Threlmark can handle those by merging changes or prompting you to resolve them. But because the data is just JSON files, conflicts are easy to spot and fix manually or automatically.
Practical Tips for Building Your Own Local-First App
If you’re inspired to build your own local-first app, start with these steps:
- Design your data as independent JSON files, one per item.
- Organize your folder structure clearly—use root manifest, project folders, and dedicated subfolders for different data types.
- Implement atomic writes for all file updates. Use rename tricks to prevent corruption.
- Use read-merge-write cycles for updates, preserving metadata and unknown fields.
- Choose sync methods—Dropbox, Syncthing, or custom WebDAV—to keep files consistent across devices.
Remember, simplicity is your friend. Keep your storage transparent, conflict handling straightforward, and the system will be resilient and easy to extend.
Frequently Asked Questions
What exactly does ‘disk is the contract’ mean?
It means the app’s core data lives directly on your device as files. These files define the system’s state and serve as the single source of truth, eliminating reliance on centralized databases or servers.
How does Threlmark handle syncing across multiple devices?
Threlmark treats the folder of JSON files as the sync point. Use tools like Dropbox or Syncthing to keep these folders in sync. When devices connect, they simply exchange files, ensuring data consistency without complex protocols.
What happens if two devices edit the same data at once?
Since each item is a separate file, conflicts are isolated. Threlmark can merge changes or flag conflicts for manual resolution. The system’s transparency makes conflict management straightforward.
Is this approach only suitable for small projects?
Not necessarily. While ideal for offline, collaborative, or multi-device workflows, large projects might require additional layering or indexing. But the core idea remains powerful for many scenarios.
Which tools or frameworks support this file-based, local-first approach?
Many modern frameworks like Electron, Tauri, or plain Node.js apps can support this. The key is designing your data as JSON files and managing atomic writes, which is straightforward with standard filesystem APIs.
Conclusion
Making the disk the contract might seem simple, but it unlocks a world of reliability, portability, and offline resilience. When your data lives in plain files, you gain clarity, control, and peace of mind.
Next time you build or pick a tool, ask: does it treat the disk as the source of truth? If yes, you’re on the right track. Your apps will be faster, safer, and more flexible — and your users will thank you for it.
